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ABOUT THIS GUIDE 
Purpose 



We've designed this Z80 Irople mentor's Guide, 
to provide the information you need to know 
in order to generate various TurboDOS config- 
urations for Z80-based microcomputers, and to 
write the driver modules for various periph- 
eral devices. This document describes the 
modular architecture and internal programming 
conventions of TurboDOS, and explains the 
procedures for system generation, serializa- 
tion, and distribution. It also provides 
detailed interface specifications for hard- 
ware-dependent driver modules, and includes 
assembler source listings of sample drivers. 



Assumptions 



Organization 



In writing this guide, we've assumed that you 
are an OEM, dealer, or sophisticated TurboDOS 
user, knowledgable in Z80-based microcomputer 
hardware and assembly-language programming. 
We've also assumed you have rea<3 both the 
User's Guide and the Z80 Programmer'.s Guider 
and are therefore familiar with the commands, 
external features, and internal functions of 
Z80 TurboDOS. 



This guide starts with a section that de- 
scribes the architecture of TurboDOS. It 
explains the function of each internal module 
of the operating system, and how these 
modules may be combined to create the various 
configurations of TurboDOS. 

The next section explains the system genera- 
tion procedure in detail, and describes each 
TurboDOS parameter which can be modified 
during system generation. 

The third section of this guide explains the 
TurboDOS distribution procedure, including 
licensing, serialization, and support. 
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Organization 
(Continued) 



Related Documents 



The fourth section is devoted to an in-depth 
discussion of internal programming conven- 
tions, aimed at the programmer writing 
drivers or resident processes for TurboDOS. 

The fifth section presents formal interface 
specifications for implementing hardware- 
dependent driver modules. 

This guide concludes with a large appendix 
containing assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for 
programmers involved in driver development. 



In addition 
interested in 



to this guide, you might be 
four other related documents: 



. TurboDOS 1*4. Usee's Guide 

. TurboDOS 1*1 M Programmer's Guide 

. TurboDOS 1*4. M.8.6 P rogramme r's Guide 

. TurboDOS 1*1 8Q86 Implementor's Guide 

You should read the first two volumes before 
start into this document. The User' s Guide 
introduces the external features and facili- 
ties of TurboDOS, and describes each TurboDOS 
command. The jL&Q. Program mer's Guide explains 
the internal workings of Z80 TurboDOS, and 
describes each operating system function in 
detail. 

You'll need the 8086 guides if you are pro- 
gramming or configuring a TurboDOS system 
that uses 8086-family microprocessors. 



TurboDOS i.4 Z80 
Implement or ' s Guide 



TABLE OF CONTENTS 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



ARCHITECTURE 



SYSTEM GENERATION 



Module Hierarchy 1-1 

Process Level s * * 1-1 

Kernel Level 1-2 

Driver Level 1-2 

TurboDOS Loader 1-2 

Module Flow Diagram 1-3 

Process Modules 1-4 

Kernel Modules 1-5 

Driver Modules 1-8 

Standard Packages 1-8 

Package Contents Table 1-9 

Additional Modules 1-10 

Memory Required 1-11 

Other Languages 1-12 

Introduction 2-1 

GEN Command 2-2 

Patch Points 2-7 

Network Operation 2-20 

Network Model 2-20 

Network Tables 2-20 

Message Forwarding 2-22 

A Complex Example 2-24 

Sysgen Procedure 2-26 

TurboDOS Licensing 3-1 

Legal Protection 3-1 

User Obligations 3-2 

Dealer Obligations 3-2 

Distributor Obligations 3-3 

Serialization 3-4 

Technical Support 3-5 

SERIAL Command 3-6 

PACKAGE Command 3-8 

Distribution Procedure 3-10 



DISTRIBUTION 



TurboDOS 1.4 Z80 
Implement or ' s Guide 



TABLE OF CONTENTS 
(Continued) 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



CODING CONVENTIONS 



DRIVER INTERFACE 



APPENDIX 



Assembler Notes 4-1 

Undefined External References 4-2 

Memory Allocation 4-3 

List Processing 4-4 

Task Dispatching 4-5 

Interrupt Service 4-7 

Poll Routines 4-8 

Mutual Exclusion 4-9 

Sample Driver Using Interrupts .... 4-10 

Sample Driver Using Polling 4-11 

Special Segments . ... . . . . , . . 4-1-2 

?INIT? Segment 4-12 

?PAGE? Segment 4-12 

?BANK? Segment 4-12 

Inter-Process Messages 4-13 

Console Routines 4-14 

Sign-On Message 4-14 

Resident Process 4-15 

User-Defined Function 4-16 

General Notes » . . 5-1 

Initialization ..... 5-2 

Console Driver 5-3 

Printer Driver 5-5 

Disk Driver 5-6 

Bank-Select Driver 5-9 

Network Driver 5-10 

Comm Driver 5-14 

Clock Driver 5-15 

Bootstrap 5-17 

Sample Driver Source Listings A-l 



TurboDOS 1.4 Z80 ARCHITECTURE 

Implementor ' s Guide 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



ARCHITECTURE This section introduces you to the internal 

architecture of the TurfcoD^^ o^erat^n s w s— 
tern. TurboDOS is highly modular, consisting 
of more than forty separate functional 
modules distributed in relocatable form. 
These modules are "building blocks" that you 
can combine in various ways to produce a 
family of compatible operating systems. This 
section describes the modules in detail, and 
describes how to combine them in various 
configurations. 

Possible TurboDOS configurations include: 

. single-user without spooling 

. single-user with spooling 

. network master 

. simple network slave (no local disks) 

. complex network slave (with local disks) 

Numerous subtle variations are possible in 
each of these categories. 



Module Hierarchy The diagram on page 1-3 illustrates how the 

functional modules of TurboDOS interact. As 
the diagram shows, the architecture of Turbo- 
DOS can be viewed as a three-level hierarchy. 



Process Level The highest level of the hierarchy is the 

process le_vjeJL. TurboDOS can support many 
concurrent processes at this level. There is 
one active process that supports the local 
user who is executing commands and programs 
in the local TPA. There are also processes 
to support users running on other computers 
and making requests of the local computer 
over the network. There are processes to 
handle background printing (de-spooling) on 
local printers. Finally, there is a process 
that periodically causes disk buffers to be 
written out to disk. 
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Kernel Level The intermediate level of the hierarchy is 

the k ernel level. The kernel supports the 
various C-functions and T-functions, and 
controls the sharing of computer resources 
such as processor time, memory, peripheral 
devices, and disk files. Processes make 
requests of the kernel through the entrypoint 
module OSNTRY, which decodes each C-function 
and T-function by number and invokes the 
appropriate kernel module. 



Driver Level The lowest level of the hierarchy is the 

driver level , and contains all the device- 
dependent drivers necessary to interface 
TurboDOS to the particular hardware being 
used. Drivers must be provided for all peri- 
pherals, including console, printers, disks, 
communications channels, and network inter- 
face. Drivers are also required for the 
real-time clock (or other periodic interrupt 
source), and for bank-switched memory (if 
applicable) . 

TurboDOS is designed to interface with almost 
any kind of peripheral hardware. It operates 
most efficiently with interrupt-driven, DMA- 
type interfaces, but can also work fine using 
polled and programmed-I/O devices. 



TurboDOS Loader The TurboDOS loader OSLOAD.COM is a program 

containing an abbreviated version of the 
kernel and drivers. Its purpose is to load 
the full TurboDOS operating system from a 
disk file (OSMASTER.SYS) into memory at each 
system cold-start. 
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Process Modules 



Jtedulg— I ^ 



bo Mvjeii 







.-Euac-Lip. 



Responsible for supporting local 
user's TPA activities. |W- W*. of^ot; f 

Contains all O/S error messages. 

Local user .option table. 
Jo hi* fftk p*+*K5 ' 

Command interpreter, processes 
commands from local user.f v * vv 

L /«€. ed.to"' r»,i ft^ *»< 4 fVs"^' 

Autoload routine which processes 
COLDSTRT.AUT and WARMSTRT. AUT. 

Routine to flush/free disk buf- 
fers at each console input. Use 
for single-user configurations 
instead of FLUSHR. 



AUTLOG Automatic log-on routine. Used 
(ofTioKH.') when full log-on security is not 
desired. See AUTUSR patch point. 



LCLUSR 

LCLMSG 
LCLTBL 
CMDINT 

AUTLOD 

SGLUSR 



SUBMIT 

NETSVC 
NETTBL 



NETFWD 

DSPOOL 
FLUSHR 



Routine to emulate CP/M proces- 
sing of $$$.SUB files. (Use is 
not recommended.) 

Services network requests from 
other processors on the network. 

Tables to define local network 
topology, used by NETSVC+NETREQ. 

Manages network message forward- 
ing. Requires NETREQ+NETSVC. 

Processes background printing. 

Periodically flushes disk buf- 
fers. Use for network master 
configuration instead of SGLUSR. I 



1-4 



TurboDOS 1.4 Z80 
Implementor ' s Guide 



ARCHITECTURE 
Kernel Modules 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Kernel Modules 




_.ElU2£jLiOXL_ „ 



\j^t Qui of 



OSNTRY 



FILMGR 

FILSUP 
FILCOM 

FILLOK 

FFOMGR 
DRVLOK 

dFASLOD 
NORLOD 
BUFMGR 

DSKMGR 

DSKTBL 

NONFIL 
COMMGR 



Kernel entrypoint module which 
decodes each C-function and 
T-function by number and invokes 
the appropriate kernel module. 

File manager responsible for 
requests involving local files. 

Support routines for FILMGR. 

Processes- common file requests 
always processed locally. 

File- and record-level interlock 
routines called by FILMGR. 

FIFO support, called by FILLOK. 

Drive interlock routines. 

Program loader incorporating an 
optimizer for fastest loading. 

Unoptimized program loader, an 
alternative to FASLOD. 

Buffer manager called by FILMGR. 
Maintains pool of disk buffers 
used to speed local file access. 

Disk manager responsible for 
physical access to local disks, 
called by BUFMGR and FASLOD. 

Table defining drives A-P as 
local or remote disk drives. 

Processes non-file functions. 

Processes comm-channel funct's. 
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Kernel Modules 
(Continued) 



I, 






bo kU^ 



CPMSUP Processes C-f unctions 7, 8, 24 , 
28, 29, 31, 37, 107 (optional). 

MPMSUP Processes C-f unctions 141-143, 
153, 160, 161 (optional). 

QUEMGR Emulates MP/M queues, supports 
C-f unctions 134-140 (optional) . 
Requires MPMSUP. 

CONMGR Responsible for console I/O. 

CONTBL Links CONMGR to console driver. 

DOMGR Responsible for do-files. 

INPLN Console input line editor used 
by CMDINT and C-f unction 10. 

LSTMGR Responsible for printer output. 

LSTTBL Table defining printers A-P and 
queues A-P as local or remote. 

SPOOLR Print spooler which diverts 
print output to a spool file 
when spooling is activated. 
Also handles direct printing to 
remote printers. 

NETREQ Responsible for issuing network 
request messages for all func- 
tions not processed locally. 

MSGFMT Network message format table 
used by NETREQ. 

NETMGR Network message routing routine 
used by NETSVC and NETREQ. 



TVO'-^S r^T/(A|vr ut. _*_% 
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Kernel Modules 
(Continued) 



Oft or v 







i Module 1 function =. I 

! i 

RTCMGR Real-time clock manager keeps 
system date and time. 

NETLOD Loads programs over the network. 

BNKMGR Responsible for bank-switching 
in banked-memory systems. 

BNKREQ Alternative to NETLOD for use in 

banked-memory systems. 5^p«A£ef of fis&Tt-oh 

DSPCHR Multi-task dispatcher which con- 
trols sharing of the local pro- 
cessor among multiple proc 

Tells c?/s # of ip/'^As -""k&T '5 ^p 

DSPSGL Null dispatcher used as alterna- 
tive to DSPCHR when only one 
process is required (OSLOAD.COM 
and single-user w/o spooling) . 



cesses. 

H' 3 '^- fitbfy^') ff'Of-^Q 



MEMMGR Memory manager responsible for 
dynamic allocation of memory. 

COMSUB Common subroutines used in all 
configurations. 

SYSNIT System initialization routine 
executed at system cold-start. 

RTCNUL Null real-time clock driver, 
used in configurations where 
there is no periodic interrupt 
source. 

CONREM Remote console driver for net- 
work master to support MASTER 
command. 

PATCH 3^28" bytes of zeroes, may be in- 
cluded to provide patch area. 
\Jon*> _ 
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Driver Modules 



-Module, J_- — -- Function 



CONDR 

LSTDR@ 

DSKDR@ 

CKTDR@ 

COMDRV 

RTCDRV 

SELBNK 

HDWNIT 



/ 



Console I/O driver. 

Printer output driver (s). 

Disk driver (s) . 

Network circuit driver (s). 

Communications channel driver. 

Real-time clock driver. 

Bank-select driver for banked- 
memory systems. 

Cold-start initialization for 
all hardware-dependent drivers, 



Standard Packages 



To simplify the system generation process, 
the most commonly-used combinations of Turbo- 
DOS modules are pre-packaged into the follow- 
ing standard configurations: 

_i > .acj£&g£__J[ — ^jasfijLjbatiojL 



STDLOADR 
STDSINGL 
STDSPOOL 
STDMASTR 
STDSLAVE 
STDSLAVX 



cold-start loader 
single-user without spooling 
single-user with spooling 
network master 

simple slave w/o local disks 
complex slave with local disks 



The contents of each standard package is 
detailed in the matrix on the facing page. 
Most TurboDOS requirements can be satisfied 
by linking the appropriate standard package 
together with a few additional optional 
modules plus the requisite driver modules. 
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Li^z *$ "'^* 



Q 



£ 5rA / ° 



'^wTLb WcXAke*, 



■ Moflml£LJ_E LI^ADR-J-.SI1SEL...±-.SEQQL...1..MASTR 1 SLAVE I SLAVX .. I 



! AUTLOD 
AUTLOG 
BNKMGR 
BNKREQ 
BUFMGR 
CMDINT 
COMMGR 
COMSUB 
CONMGR 
CONREM 
CONTBL 
CPMSUP 
DOMGR 
DRVLOK 
DSKMGR 
DSKTBL 
DSPCHR 
DSPOOL 
DSPSGL 
FASLOD 
FFOMGR 
FILCOM 
FILLOK 
FILMGR 
FILSUP 
FLUSHR 
INPLN 
LCLMSG 
LCLTBL 
LCLUSR 
LDRMSG 
LSTMGR 
LSTTBL 
MEMMGR 
MPMSUP 
MSGFMT 
NETFWD 
NETLOD 
NETMGR 
NETREQ 
NETSVC 



.2 

.0 

2.0 

.3 

1.1 

1.3 

.1 

.3 

.3 

.4 

.0 

.2 

.4 

.2 

.6 

.0 

.7 

.9 

.2 

.4 

.9 

.4 

1.7 

2.1 

2.4 

.2 

.1 

.4 

.0 

1.2 

.2 

.2 

.1 

9 O 

.1 
.1 

.3 

.4 

.9 

1.5 

1.7 



BUFMGR 



COMSUB 
CONMGR 

CONTBL 



DSKMGR 
DSKTBL 



DSPSGL 



LDRMSG 



AUTLOD AUTLOD 
AUTLOG AUTLOG 
+ + 



BUFMGR 
CMDINT 
COMMGR 
COMSUB 
CONMGR 

CONTBL 

+ 
DOMGR 

DSKMGR 
DSKTBL 



DSPSGL 

+ 



FILMGR FILMGR 
FILSUP FILSUP 

INPLN 
LCLMSG 
LCLTBL 
LCLUSR 



LSTMGR 
LSTTBL 
MEMMGR 

+ 



BUFMGR 
CMDINT 
COMMGR 
COMSUB 
CONMGR 

CONTBL 

+ 
DOMGR 

DSKMGR 
DSKTBL 
DSPCHR 
DSPOOL 

+ 



FILCOM FILCOM FILCOM 



FILMGR 
FILSUP 

INPLN 
LCLMSG 
LCLTBL 
LCLUSR 

LSTMGR 
LSTTBL 
MEMMGR 

+ 



AUTLOD 
AUTLOG 

+ 

+ 
BUFMGR 
CMDINT 
COMMGR 
COMSUB 
CONMGR 

+ 
CONTBL 

+ 
DOMGR 
DRVLOK 
DSKMGR 
DSKTBL 
DSPCHR 
DSPOOL 

+ 
FFOMGR 
FILCOM 
FILLOK 
FILMGR 
FILSUP 
FLUSHR 
INPLN 
LCLMSG 
LCLTBL 
LCLUSR 

LSTMGR 
LSTTBL 
MEMMGR 

+ 

+ 

+ 

+ 
NETMGR 

+ 
NETSVC 



AUTLOD 


AUTLOD ! 


AUTLOG 


AUTLOG i 


+ 


+ 1 


+ 


+ 1 


- 


BUFMGR 1 


CMDINT 


CMDINT 1 


COMMGR 


COMMGR i 


COMSUB 


COMSUB 1 


CONMGR 


CONMGR 1 


CONTBL 


CONTBL 1 


+ 


+ 1 


DOMGR 


DOMGR 1 


— 


DSKMGR 1 


DSKTBL 


DSKTBL 1 


DSPCHR 


DSPCHR 1 


— 


DSPOOL 1 


+ 


+ 1 


FILCOM 


FILCOM 1 


— 


FILMGR 1 


- 


FILSUP 1 


INPLN 


INPLN 1 


LCLMSG 


LCLMSG 1 


LCLTBL 


LCLTBL 1 


LCLUSR 


LCLUSR 1 


LSTMGR 


LSTMGR 1 


LSTTBL 


LSTTBL 1 


MEMMGR 


MEMMGR ! 


+ 


+ 1 


MSGFMT 


MSGFMT 1 


+ 


+ 1 


+ 


+ 1 


NETMGR 


NETMGR 1 


NETREQ 


NETREQ 1 


+ 


+ 1 




NETTBL_ 1 



4" fl^~s iLV 4>i* ? -" o 
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l_Hfidiilfi_JL 


_iL_.L 


LOADR 1 


..SIHGL , I 


"spool \ 


Lmasibl-L 


-^IiZffiE_J-SLASZ2L-. 1 


1 NONFIL 


.2 


NONFIL 


NONFIL 


NONFIL 


NONFIL 


NONFIL 


NONFIL 1 


1 NORLOD 


.1 


- 


+ 


+ 


+ 


+ 


+ I 


1 OSLOAD 


1.3 


OSLOAD 


- 


- 


- 


- 


- | 


1 OSNTRY 


.5 


OSNTRY 


OSNTRY 


OSNTRY 


OSNTRY 


OSNTRY 


OSNTRY 1 


1 PATCH 


.1 


+ 


+ 


+ 


+ 


+ 


+ I 


1 QUEMGR 


1.1 


- 


- 


- 


+ 


+ 


+ I 


1 RTCMGR 


.1 


- 


RTCMGR 


RTCMGR 


RTCMGR 


- 


RTCMGR 1 


1 RTCNUL 


.1 


+ 


+ 


+ 


+ 


+ 


+ 1 


1 SGLUSR 


.1 


- 


SGLUSR 


SGLUSR 


- 


- 


SGLUSR 1 


1 SPLMSG 


.1 


- 


- 


SPLMSG 


SPLMSG 


SPLMSG 


SPLMSG 1 


1 SPOOLR 


.5 


- 


- 


SPOOLR 


SPOOLR 


SPOOLR 


SPOOLR 1 


1 SUBMIT 


.1 


- 


+ 


+ 


+ 


+ 


+ 1 


1 SYSNIT.. , 


.0 


- 


-SXSHI3L. 


sxsmjL. 


«SISNI3L-JSXfilUaL 


-SXSHIT-J 



Optional Modules 



To supplement the standard packages, certain 
optional modules (marked by "+" in the matrix 
above) may have to be added. The following 
table explains where these optional modules 
are required: 



_lfodlilfi,-L_. 



JKhfi rfi-Jtequir ed „ 



BNKMGR 

BNKREQ 

CONREM 

CPMSUP 

FASLOD 

MPMSUP 

MSGFMT 

NETFWD 

NETLOD 

NETREQ 

NORLOD 

PATCH 

QUEMGR 

RTCNUL 

SUBMIT 



All systems with banked memory. 

Banked systems that load programs over the network. 
Network masters with no console (instead of CONDR@) . 
To support C-fcns 7, 8, 24, 28, 29, 31, 37 and 107. 
Non-banked systems that load pgms from local disks. 
To support C-fcns 134-143, 153, 160 and 161. 
Network masters that make requests over the network. 
To support forwarding of network messages. 
Non-banked systems that load pgms over the network. 
Network masters that make requests over the network. 
Smaller, unoptimized alternative to FASLOD (above). 
Wherever a supplementary patch area is required. 
To support MP/M queue emulation (C-fcns 134-140.) 
Wherever no RTC driver is available. 
To emulate CP/M processing of $$$.SUB. 
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Memory Required 






y 



X 



^ v/ 



^ 



~i 



o 



t* 



To estimate the memory required by a particu- 
J.*-*, j. wi. K/v^i^ou v,vniiyuLaLiun f yuu neea to taKe 
into account the combined size of all func- 
tional modules, driver modules, disk buffers, 
and other dynamic storage. 

Drivers typically require IK to 4K, and can 
be even larger if the hardware is especially 
complex. Disk buffer space should be as 
large as possible for optimum performance, 
especially in a network master. About 4K of 
disk buffer space is reasonable for a single- 
user system, although less can be used in a 
pinch. Other dynamic storage doesn't usually 
exceed IK in single-user systems, 2K in net- 
work masters. 



The following table gives typical memory 
requirements for standard TurboDOS configura- 
tions on non-banked hardware: 



O/S 10K 
Drivers 2K 
Buffers 4K 
Dynamic IK 



Total 
TPA 



17K 



13K 
2K 
4K 
IK 



20K 
44K 



15K 
2K 
4K 
IK 



22K 
42K 



20K 
3K 

16K 
3K 



42K 
22K 



10K 
IK 

2K 



13K 
51K 



18K 
2K 
4K 
2K 



26K 
38K 






In banked-memory systems, a full 63K TPA is 
always available. 
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Other Languages 



To facilitate translation into languages 
other than English, TurboDOS has been imple- 
mented with all textual messages segregated 
into separate modules. All such message 
modules are available in source form to 
TurboDOS OEM licensees upon request. 

The following modules contain all TurboDOS 
operating system messages: 



_J5s£ille__L„_„__ X-ftnfcains 

LCLMSG Most operating system messages. 

SPLMSG Spooler error messages. 

LDRMSG Loader messages for OSLOAD.COM. 



In addition, a separate message module is 
available for each TurboDOS command. 
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Process Level 



Despool Lfil_JIfi£ ELe.t.,figg. Buffers, 

DSPOOL LCLUSR NETSVC FLUSHR 

LCLMSG NETTBL 

LCLTBL NETFWD 



Loadex_. 

OSLOAD 

LDRMSG 



CMDINT 
AUTLOD 
SGLUSR 
AUTLOG 
SUBMIT 

1 

I 



Kernel Level 



_Bank_ 
BNKMGR 
BNKREQ 
I 



I 

-JltJafiLE— 

NONFIL 
CPMSUP 
MPMSUP 
QUEMGR 

I 

I 

I 



*^ ^* ^^ ^^ N*^j 

OSNTRY 

__L. 

I I I 

_Xils_ nausea _£l££Js_ 

FILMGR NETMGR RTCMGR 
FILSUP NETREQ 
FILCOM MSGFMT 
FILLOK NETTBL 
FFOMGR NETLOD 
DRVLOK 
FASLOD 
NORLOD 



I I I 
I COMMGR LSTMGR 



LSTTBL 
SPOOLR 
SPLMSG 

I 
| 



CONMGR BUFMGR 

CONTBL DSKMGR 

DOMGR DSKTBL 
INPLN 

I 
| 



I 
S.UPPQJLt. 
DSPCHR 
DSPSGL 
MEMMGR 
COMSUB 



Initial 

SYSNIT 



Driver Level I 

I I I 

I Comm_._Ch Pxintex 

I COMDRV LSTDRA 

. Bank, LSTDRB 

SELBNK etc. 



I 
Console ..Disk IfeJazfliLk _£lQ£Js_. Initial 

CONDRA DSKDRA CKTDRA RTCDRV HDWNIT 

or DSKDRB CKTDRB or 
CONREM etc. etc. RTCNUL 
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SYSTEM GENERATION 



This section explains the TurboDOS system 
n 6R6rstioR Procedure in detail* It describes 
how to use the GEN command to link a desired 
set of TurboDOS modules together, and details 
the numerous system patch points which may be 
modified during system generation. Step-by- 
step procedures and examples are provided. 



Introduction 



The functional modules of TurboDOS are 
distributed in relocatable form (.REL files). 
Hardware-dependent driver modules are fur- 
nished in the same fashion. The TurboDOS GEN 
command is a specialized linker used to bind 
the desired combination of modules together 
into an executable version of TurboDOS. The 
GEN command also includes a symbolic patch 
facility used to modify a variety of opera- 
ting system parameters. 

To generate a complete TurboDOS system, you 
typically must use the GEN command several 
times. At minimum, you have to generate both 
a loader OSLOAD.COM and a master operating 
system OSMASTER.SYS. For a networking system 
you also have to generate a slave operating 
system OSSLAVE.SYS. Complex networks may 
require generation of several different slave 
or master configurations. Finally, you may 
have to use GEN to generate a cold-start 
bootstrap routine for the start-up PROM or 
boot track. 

At cold-start, the bootstrap routine loads 
the loader program 0SL0AD.COM into the TPA of 
the master computer and executes it. 0SL0AD 
loads the master operating system from the 
file OSMASTER.SYS into the upper portion of 
memory. The master operating system then 
down-loads the slave operating system from 
the file OSSLAVE.SYS over the network into 
each slave computer. 



2-1 



TurboDOS 1.4 Z80 SYSTEM GENERATION 

Implementor ■ s Guide 

GEN Command 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 

GEN Command The GEN command is a specialized linker for 

software modules in Microsoft relocatable 
format, and is designed primarily for use in 
TurboDOS system generation. 

Syntax I I 

I GEN srcefile {destfile} (;options) I 

Explanation The GEN command links a specified collection 

of relocatable modules together into a single 
executable program. The "srcefile" argument 
specifies the names of two input files: a 
configuration file "srcefile. GEN" and a para- 
meter file "srcefile. PAR". The "destfile" 
argument specifies the name of the executable 
output file to be created (normally type .COM 
or .SYS). If "destfile" is omitted, then the 
"srcefile" argument is also used as the name 
of the executable output file, and should 
include an explicit file type (.COM or .SYS). 

If the configuration file "srcefile. GEN" is 
found, it must contain the list of reloca- 
table modules (.REL files) to be linked 
together. If the configuration file is not 
found, then the GEN command operates in an 
interactive mode. You are prompted by an 
asterisk * to enter a series of directives 
from the console. The syntax of each direc- 
tive is: 

_____________ ___ _ ___ ^ 

comment) I 
, . 1 

A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, GEN links all of the modules 
together, a two-pass process that displays 
the name of each module as it is encountered. 
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Explanation When the linking phase is complete, GEN looks 
(Continued) for a parameter file "srcef ile.PAR" and pro- 
cesses it if found. The parameter file (if 
present) must be a text file containing sym- 
bolic patches. The syntax of each .PAR file 
entry is: 

I location = value {, value}... {; comment} I 

where the "value" arguments are to be stored 
in consecutive memory locations starting with 
the address specified by "location". 

The "location" argument may be the name of a 
public symbol, a hexadecimal number, or an 
expression composed of names and hex numbers 
connected by + or - operators. Hex numbers 
must begin with a digit (for example, OFFFF) 
to distinguish them from names. The "loca- 
tion" expression must be followed by an 
equal-sign = character. 

The "value" arguments may be expressions (as 
defined above) or quoted ASCII strings, and 
must be separated by commas. A "value" 
expression is stored as a 16-bit word if its 
value exceeds 255 or if it is enclosed in 
parentheses; otherwise, it is stored as an 8- 
bit byte. A quoted ASCII string may be 
enclosed by either quotes "..." or apostro- 
phes '...', and is stored as a sequence of 8- 
bit bytes. Within a quoted string, ASCII 
control characters may be specified by using 
circumflex (example: ""X" denotes CTRL-X). 

After the .PAR file (if any) is processed and 
the necessary patches made, GEN writes the 
executable file out to disk. 



2-3 



TurboDOS 1.4 Z80 
Implementor ■ s Guide 



SYSTEM GENERATION 

GEN Command 
(Continued) 



Copyright 1984 by Software 2000, Inc 
All rights reserved. 



Explanation 
(Continued) 



Options 



F '■'■'■ 



Each relocatable TurboDOS module is magnetic- 
ally serialized with a unique serial number. 
The serial number consists of two components: 
an "origin number" which identifies the 
issuing TurboDOS licensee, and a "unit 
number" which uniquely identifies each copy 
of TurboDOS issued by that licensee. The GEN 
command verifies that all modules to be 
linked are serialized consistently, and 
serializes the executable file accordingly. 



■jQpivic-JLJ- „. 



?J^LQaJJLojl-___ . 



;Kxxxx 

: zftoo 

J, fOOtP 



;M 
;s 

;Uxxxx 



;x 



Indicates that a system for a 
banked-memory environment is to 
be generated, and defines the 
hexadecimal base address "xxxx" 
of the common (non-switched) 
memory segment. 



;Lxxxx Defines the hexadecimal address 
"xxxx" as the lower boundary of 
the executable program. Default 
for .COM files is ;L0100. 



Prints a load map. 

Prints a sorted symbol table. 

Defines the hexadecimal address 
"xxxx" as the upper boundary of 
the executable program. Default 
for .SYS files is ;UFFFF. 

Diagnoses any references to un- 
defined symbols. Default is not 
to diagnose such references, 
since they are quite normal in 
TurboDOS system generation. 
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In the following example, GEN is used to link 
a single-user TurboDOS system for a banked- 
memory system, using the modules listed in 
BNKSINGL.GEN and the patches in BNKSINGL.PAR, 
creating the executable file BNKSINGL. SYS. 



0A>GSN BNKSINGL, SYS... rMOLQi?. 
Copyright 1984, Software 2000, Inc. 



CNFTBL 

STDSINGL 

BNKMGR 

CPMSUP 

USRSOM 

NITIMS 

MPENIT 

CON96 

LSTCTS 

LSTXON 

etc. 



CONFIGURATION TABLE 
STANDARD SINGLE-USER SYSTEM 
BANK MEMORY MANAGER 
CP/M FUNCTION SUPPORT 
USER SIGN-ON MESSAGE AREA 
HARDWARE INITIALIZATION 
MEMORY PARITY 

ASCII CONSOLE AT 9600 BAUD 
CLEAR TO SEND SERIAL DRIVER 
X-ON,X-OFF SERIAL DRIVER 



Pass 1 

CONFIG LCLUSR LCLMSG LCLTBL CMDINT etc. 

Pass 2 

CONFIG LCLUSR LCLMSG LCLTBL CMDINT etc. 



Process 
USRSOM 

AUTUSR 
COMPAT 
PRTMOD 
NMBUFS 
SRT401 



ing parameter file: 

= 0D,0A,"IMS International, 

TurboDOS-8 1.4 (Bank Single) $" 



80 

0B0 



2 

6 



SRT431 = 6 



etc. 



LOGON TO USER 0, PRIVILEDGED 
COMPATIBILITY FLAGS 
DEFAULT TO PRINT DIRECT 
NUMBER BUFFERS (2) 
6 MS. STEP RATE FOR 8" 
DRIVES ON 401 CONTROLLER 
12 MS. STEP RATE FOR 5" 
DRIVES ON 431 CONTROLLER 



Writing output file A: BNKSINGL. SYS 
0A} 
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Error Messages 



File name missing from command 

Invalid input file name 

Non-privileged user 

Serial number violation 

Not enough memory 

Vacuous input file(s) 

Unexpected EOF in input file 

Disk is full 

Can't make output file 

No input files 

Can't open input file 

Load address out-of-bounds 

Multiple defined starting address 

Duplicate symbol: <name> 

Undefined symbol: <name> 
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Patch Points 



The following table describes various public 
ojfiuuwxo xii iuiuufuo wiij.'uii yuu may wxan to 
modify using the symbolic patch facility of 
the GEN command. (Other patch points may 
exist in hardware-dependent drivers, but they 
are beyond the scope of this document.) 

ABTCHR = ""C" CONTBL 

Abort character (after attention) . 



ATNBEL = ""G" CONTBL 

Attention-received warning character. 



ATNCHR = 



CONTBL 



Attention character. May be patched to 
another character if the default value of 
CTRL-S is needed by application programs. 
A common choice is zero (NUL) , which al- 
lows the console BREAK key to be used as 
an attention key. 



AUTUSR = OFF 



AUTLOG 



Automatic log-on user number. Default 
value of OFF requires that user log-on 
via LOGON command. If automatic log-on 
desired at cold-start, patch AUTUSR to 
the desired user number (00-1F) , and set 
the sign-bit if a privileged log-on is 
desired. Generally patched to 80 in 
single-user systems to cause automatic 
privileged log-on to user zero. 
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Patch Points 
(Continued) 



^J^fauliL.Jfalue_ _ LMos&xl£-~ 

BFLDLY = (012C) FLUSHR 

Buffer flush delay determines how often 
disk buffers are written to disk, stated 
in system "ticks". Default value (300 
decimal) causes buffers to be flushed 
about every five seconds (assuming 60 
ticks per second) . y v c ^ n*ck- >t f**^ 0/ &*'+*$ 



BUFSIZ = 3 



BUFMGR 



Default disk buffer size (0=128, 1=256, 
2=512, 3=1K,..., 7=16K). Default value 
specifies IK disk buffers. 

MfWft ..y?.'?£..0.5 . y. /? H ^; A iy..". 



CKTAST = (0000) ,CKTDRA, NETTBL 

(0100) ,CKTDRB, 
(0200) ,CKTDRC, 
(0300) ,CKTDRD 

Circuit assignment table defines network 
topology. Contains NMBCKT two-word en- 
tries, one for each network circuit to 
which this processor is attached. The 
first word of each entry specifies the 
network address by which this processor 
is known on a particular circuit, and the 
second word specifies the entrypoint ad- 
dress of the circuit driver responsible 
for that circuit. (Possibly several cir- 
cuits may be handled by the same driver.) 



CLBLEN = 9D 



■? 



&0 



J. D 



CMDINT 



Command line buffer length defines long- 
est permissible command line. The de- 
fault value permits two 80-char lines. 
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Patch Points 
(Continued) 



-Symbol-, J„ J)^f3iUJ^iZiiU£--___JLiloj|iile_ 

CLPCHR = "}" CMDINT 

Command line prompt character. 



CMDINT 



Command line separator character. 



COLDFN = 0, "COLDSTRT n f "AUT" 



AUTLOD 



File name and drive for cold-start auto- 
load processing (in FCB format). 



COMPAT = 



FILCOM 



Default compatibility flags which define 
rules to be used for file-sharing. Patch 
to 0F8 to relax most MP/M restrictions. 



CONTBL 




CONAST = (f,CONDRA 



Console assignment table defines how con- 
sole I/O is handled. First byte passed 
to console driver, and commonly defines 
the channel number (e.g., serial port) to 
be used for the console. Following word 
specifies the entrypoint address of the 
console driver to be used. 



CPMVER =31 



NONFIL 



CP/M BDOS version number returned by 
C-f unction 12 in L-register. 
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Patch Points 
(Continued) 



CURBNK = 1 



BNKMGR 



Initial memory bank selected for TPA at 
cold-start. Applicable to banked-memory 
systems only. Patch to to select non- 
banked mode at cold-start. 



DEFDID = (0000) 



NETTBL 



Default network destination ID, used for 
routing all network requests that are not 
related to a particular disk drive, queue 
or printer. In a slave, DEFDID should be 
set to the network address of the master. 



DSKAST = 00,DSKDRA,01,DSKDRB, DSKTBL 
OFF, (0000) ,0FF, (0000) ,... 

Disk assignment table, an array of 16 
three-byte entries (one for each drive 
letter A-P) that defines which drives are 
local, remote, and invalid. 

For a local drive, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk driver, and is common- 
ly used to differentiate between multiple 
drives connected to a single controller. 
The following word specifies the entry- 
point address of the disk driver to be 
used. 

For a remote drive, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the drive let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 
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I Symbol 1 J)^fauJJ;.,.ValHe_ LUfidalfL- I 

■ i 

i i 

DSKAST (Continued) DSKTBL 

For an invalid drive, the first byte must 
be OFF, and the following word should be 
(0000) . 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

DSKAST = 80,(0000) ,81, (0000) , 
82,(0000) ,83,(0000) , 
...,8E,(0000) ,8F,(0000) 



DSPPAT = 01,01,01,... ,01 



LSTTBL 



De-spool printer assignment table, an ar- 
ray of 16 bytes (one for each printer 
letter A-P) that defines the initial 
queue to which each printer is assigned. 
Hex values 01 through 10 correspond to 
queues A-P, and means that the printer 
is off-line. The default value assigns , 
all printers to queue A. pf?5/f'cM Hprthotis 
_ fi r "vt^ . Tk.-.y/ftW ,fc pA&Ai _,JH._^_M^y< i , 



ECOCHR = 



CONTBL 



Echo-print character (after attention) . 



EOPCHR = 



LSTTBL 



End-of-print character. May be patched 
to any non-null character, in which case 
the presence of that character in the 
print output stream will automatically 
signal an end-of-print-job condition. 
The value zero disables this feature. , n 



ifU. 
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Patch Points 
(Continued) 



//J * ^ J ' , \ k 






pJ^J . -JJefauIiLJialiifi. 



._J_Jtodula. 



FWDTBL = ftiTF F - P) , (OFFFF) , (OFFFF) , NETTBL 
<0FFFF) ,0FF- 
Otfr, Out? 

Network forwarding table, an array of 
two-byte entries that define any explicit 
message forwarding routes to be used by 
this processor. The first byte of each 
entry specifies a "foreign" circuit num- 
ber N, and the second byte a "domestic" 
circuit number C. Any messages destined 
for circuit N will be routed via circuit 
C. This table is variable-length, termi- 
nated by OFF, and defaults to empty. 



LDCOLD = OFF 



AUTLOD 



Cold-start autoload enable flag. Patch 
to zero if you want to disable the cold- 
start autoload feature (COLDSTRT. AUT) . 



LDWARM = OFF 



AUTLOD 



Warm-start autoload enable flag. Patch 
to zero if you want to disable the warm- 
start autoload feature (WARMSTRT. AUT) . 



LOADFN = 0,"OSMASTER","SYS" 



OSLOAD 



Default file name and drive (in FCB for- 
mat) loaded by OSLOAD.COM. Drive field 
(FCB byte 0) may be patched to an expli- 
cit drive value to inhibit scanning. 
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Patch Points 
(Continued) 










k0 cw. 



L-gymboJ-J.. 



logusr = IF 



i 

FILCOM 



User number for logged-off state. De- 
fault value is 31 decimal. 



MAXMBS = NETMGR 

Maximum number of message buffers that 
will ever be allocated. Default value of 
means number of message buffers is 
limited only to size of available memory. 



MAXRPS = 



NETMGR 



Maximum number of reply packets that will 
ever be allocated. Default value of 
means number of reply packets is limited 
only to the size of available memory. 



MEMBLL = (1100) \^-pro H &U^S »f o/s MEMMGR 

Memory base lower limit, prevents alloca- 
tion of dynamic memory space below this 
address when bank is selected. Default 
value guarantees minimum of 4K TPA in 
bank (enough to run BANK or BUFFERS) . 
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Patch Points 
(Continued) 






,xV 



K 



^ 



^, N> 



5 ft 



iT 



VO" 



Sa- 










* to* 



§A 






H ut0OV\ , 



Xv? • 



9- 






v 3,/cl >2J> 






V 



'/, 



\ 



Symbol J J3££aiLL±_, 

MEMRES = (0100) 



LJlGdille-„ 

LCLUSR 



Memory reserve, used when loading a pro- 
gram into TPA to provide a safety margin 
between the base of dynamic memory space 
and the top of bank TPA. This allows 
dynamic space to grow by MEMRES bytes 
before the program in bank TPA has to 
be aborted by TurboDOS. The MEMRES value 
may have to be increased above the 256- 
byte default value for reliable operation 
especially in non-banked network masters. 



MEMTOP = (0FFFF) 



OSLOAD 



Top of memory address for purposes of the 
RAM diagnostic test performed by OSLOAD. 
Patch to (0000) to omit test altogether. 



NMBCKT = 1 



NETTBL 



Number of network circuits to which this 
processor is connected. 



NMBMBS = 



NETMGR 



Number of message buffers pre-allocated 
at cold-start. Message buffers are allo- 
cated dynamically as needed, but this may 
cause fragmentation which prevents you 
from obtaining more TPA by reducing the 
size of the disk buffer pool. If this is 
important, patching NMBMBS to a suitable 
positive value will eliminate the problem 
(twice the number of network nodes is a 
good starting value to try) . 
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L.fiymfrQJL_L Default Value I Module I 



AJft 



NMBRPS = 



NETMGR 



Number of reply packets pre-allocated at 
cold-start. Reply packets are allocated 
dynamically as needed, but this may cause 
fragmentation which prevents you from ob- 
taining more TPA by reducing the size of 
the disk buffer pool. If this is impor- 
tant, patching NMBRPS to a suitable posi- 
tive value will eliminate the problem. 
(The number of network nodes is a good 
starting value to try.) 



NMBSVC = 2 



t*h circuit 



•bw.te-fm e*i circuiT NETSVC 

polth*. 

Number of network server processes to be 
activated. (The number of network nodes 
is a good starting value to try.) 

/^>4j>y_v Ji ±_ J$ */_ 3>ky?y ty $+** . * _"fe£'_ 



NMBUFS = 4 



BUFMGR 



Default number of disk buffers allocated 
at cold-start. Must be at least 2. For 
optimum performance, allocate as many 
buffers as possible (consistent with TPA 
and other memory requirements) . 



PRTCHR = 



'L n 



CONTBL 



End-print character (after attention) . 
This is a console attention-response, not 
to be confused with EOPCHR. 
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„£yjakoJLJ 

PRTMOD = 1 



D£fAUl±_Jfalue Lilfidnle— 

LCLTBL 



Initial print mode for local user. The 
default value of 1 specifies spooling. 
Patch to for direct, or 2 for console. 



PTRAST = 00,LSTDRA,0FF, (0000) , LSTTBL 
OFF, (0000) ,0FF, (0000) , . . . 

Printer assignment table, an array of 16 
three-byte entries (one for each printer 
letter A-P) that defines which printers 
are local, remote, and invalid. 

For a local printer, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk printerr, and is com- 
monly defines the channel number (e.g., 
serial port) to be used for the printer. 
The following word specifies the entry- 
point address of the printer driver to be 
used. 

For a remote printer, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the printer 
letter to be accessed on the remote pro- 
cessor. The following word specifies the 
network address of the remote processor. 

For an invalid printer^ the entry should 
be OFF, (0000) . 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

PTRAST » 80,(0000) ,81,(0000) , 
82,(0000) ,83,(0000) , 
...,8E,(0000) ,8F,(0000) 
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1. -Symbol. J Da£aulfc..yalHfi 1. Module I 

j j 

QUEAST = 00 f (0000) f 0FF, (0000) , LSTTBL 
OFF, (0000) , OFF, (0000) ,... 

Queue assignment table, an array of 16 
three-byte entries (one for each queue 
letter A-P) that defines which queues are 
local, remote, and invalid. 

For a local queue, all three bytes must 
be set to zero. 

For a remote queue, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the queue let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 

For an invalid queue, the entry should be 
OFF, (0000). 

NOTE: In slave configurations STDSLAVE 
and STDSLAVX, the default values are: 

QUEAST = 80,(0000) ,81,(0000) , 
82,(0000) ,83,(0000) , 
...,8E, (0000) ,8F, (0000) 



QUEDLY = (0000) 



QUEMGR 



Polling delay used in unconditional Read 
Queue (when queue is empty) and Write 
Queue (when queue is full) , stated in 
system "ticks". If RTC driver is avail- 
able, patch to largest delay that yields 
reasonable queue performance. 
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Patch Points 
(Continued) 



„£yjnkPl_J J3&£ault Value. LflQjflulfL . 

QUEDRV = OFF QUEMGR 

Drive used for FIFOs that emulate MP/M 
queues. Default value OFF means use the 
system disk (disk from which TurboDOS was 
loaded at cold-start) . Patch to 00 - OF 
to specify a particular drive A-P. 



QUEPTR = 1 



LCLTBL 



Initial queue or printer assignment. If 
PRTMOD = 1 (spooling), QUEPTR specifies a 
queue assignment. If PRTMOD = (direct) 
QUEPTR specifies a printer assignment. 
In both cases, hex values 01 through 10 
correspond to letters A-P, and zero means 
do not queue or print off-line. 



RCNMSK = OFF 



MPMSUP 



Mask used in deriving a console number 
from a network node in C-f unction 153. 



RCNOFF = 



MPMSUP 



Offset used in deriving a console number 
from a network node in C-f unction 153. 



RESCHR = ""Q" CONTBL 

Resume character (after attention) . 
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) £ll J Pjifa_ujj:_ J£aln£. 

SCANDN = 



Module. 



OSLOAD 



Scan direction flag for OSLOAD. Patch to 
OFFH to scan P-to-A (instead of A-to-P) . 



SLVFN = "OSSLAVE n f n SYS" 



NETSVC 




Name and type of file (in FCB format) to 
be down-loaded into slave processors. 



SPLDRV = OFF 



LCLTBL 



Initial spool drive. Default value OFF 
spools to system disk (from which Turbo- 
DOS was loaded at cold-start) . Patch to 
00 - OF to specify a drive A-P. 



SRHDRV = 



CMDlNT 



Search drive for command files. Patch to 
01 - 10 hex to search drive A-P if com- 
mand is not found on current drive, or 
patch tO OFF to search system disk (from 
which TurboDOS was loaded at cold-start) . 
Default value disables this feature. 



SUBFN = 0,"$$$ 



'V'SUB" 



SUBMIT 



Submit file name searched for by optional 
CP/M submit-file emulator. 



WARMFN = 0,"WARMSTRT ,, , n AUT n 



AUTLOD 



File name and drive for warm-start auto- 
load processing (in FCB format). 



Vo 



$ 
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Network Operation 



TurboDOS accomodates a wide variety of net- 
work topologies, ranging from the simplest 
point-to-point master/slave networks to the 
most complex star, ring, and hierarchical 
structures. 



Network Model 



A TurboDOS network is defined to consist of 
up to 255 circuits . with up to 255 n.P.de,.s, 
(processors) on each circuit. Each node has 
a unique 16-bit network address consisting of 
an 8-bit circuit number plus an 8-bit node 
number (on that circuit). 

Any processor may be connected to several 
circuits, if desired. A processor connected 
to multiple circuits has multiple network 
addresses, one for each circuit. Such a 
processor even may be set up to perform mes- 
sage forwarding from one circuit to another, 
permitting dialogue between network nodes 
that do not share a common circuit between 
them (more on this later) . 



Network Tables 



The actual network topology is defined by a 
series of tables in each processor. The 
tables are set up during system generation, 
and define the network as "seen" from the 
viewpoint of each processor. The tables are: 



Symbol 



NMBCKT 



.„D&£Cj 



LiOJl 



A byte value that defines the 
number of network circuits to 
which this processor is connec- 
ted. 
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Network Tables 



I _ .Symbol J Description 

CKTAST The circuit assignment table 

containing NMBCKT entries defin- 
ing the network address by which 
this processor is known on each 
circuit, and specifying the net- 
work circuit driver responsible 
for each handling each circuit. 

DSKAST The disk assignment table that 
specifies for all drive letters 
A-P which are local, remote, and 
invalid. This table specifies 
a network address for each re- 
mote drive, and a disk driver 
for each local drive. 

PTRAST The printer assignment table 

that specifies for all printer 
letters A-P which are local, re- 
mote, and invalid. This table 
specifies a network address for 
each remote printer, and a prin- 
ter driver for each local prin- 
ter. 

QUEAST The queue assignment table that 
specifies for all queue letters 
A-P which are local, remote, and 
invalid. This table specifies a 
network address for each remote 
queue. 

DEFDID The default network destination 
ID, used for routing all network 
requests that are not related to 
a specific disk drive, printer, 
or queue. 
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Network Tables 
(Continued) 



Symbol. J Ke^.cj.lp.fciQiL. 



FWDTBL The message forwarding table 
that specifies any additional 
circuits (not directly connected 
to this processor) which may be 
accessed via explicit message 
forwarding, and how messages 
destined for such circuits are 
to be routed. 



These tables are pre-defined with default 
values to make set-up of simple master/slave 
networks very easy. For complex multi- 
circuit networks, the set-up is somewhat more 
complicated (as might be expected). 

Refer to the preceding Patch Points sub- 
section for details of the organization and 
defaults for these network tables. 
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Message Forwarding The forwarding module of TurboDOS (NETFWD) 

Rlinnnrfs hni-h "lmnlirif 11 an^ "ovnlin^" -F/^r--. 

— — £^£" "~ — — ~» ~- — ■ w*i -■- Ill £» -1. J. V J. «_ U11U ^ A £S .1. J. V J. b. JL Vi. 

warding of network messages. To understand 
the distinction, consider the case of a net- 
work with three processors (PI, P2, and P3) 
connected by two circuits (CI and C2) as 
follows: 




A program running in PI makes an access to 
drive D. Suppose the disk assignment tables 
in the three processors are set up in the 
following fashion: 

Pi's DSKAST defines its drive D as a 
remote reference to P2's drive B. 

P2's DSKAST defines its drive B as a 
remote reference to P3's drive A. 

P3's DSKAST defines its drive A as a 
local device attached directly to P3. 

In this case, Pi's access to its drive D 
actually winds up implicitly accessing P3's 
drive A. This is implicit forwarding. 

Alternatively, suppose Pi's DSKAST defines 
its drive D as a remote reference to P3's 
drive A, and that Pi's FWDTBL provides that 
messages destined for circuit C2 may be 
routed via CI. In this case, PI sends a 
request to P3 on circuit CI. P2 receives the 
request, recognizes that it should be forwar- 
ded, and retransmits the request to P3 via 
circuit C2. Thus, PI accesses P3*s drive A 
with the assistance of P2, but this time PI 
is not aware of P2's role in the transaction. 
This is explicit forwarding. 
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A Complex Example Let's take a reasonably complex network situ- 
ation and see how to construct the required 
.GEN and .PAR files. 

Our hardware is an S-100 microcomputer system 
consisting of a Z80 CPU board, a 64K memory 
board, hard disk and floppy disk controller 
boards (all these make up the master proces- 
sor), and several single-board slave proces- 
sors on the same bus. The master processor 
is interfaced to two printers, one r daisy wheel 
and the other matrix, via RS232 serial ports. 
The daisywheel printer is on serial port 
and uses XON/XOFF protocol, while the matrix 
printer is on port 1 and uses clear-to-send 
handshaking. In addition, the master has a 
high-speed RS422 interface connecting it to 
another S-100 system of similar configuration 
some distance away. 

We want to configure a TurboDOS system for 
this hardware that permits all of the users 
of each S-100 system to access the hard disk, 
floppy disks, and printers attached to both 
the local and remote S-100 system. We might 
create the following OSMASTER.GEN file: 



; OSMASTER 

STDMASTR 

FASLOD 

NETREQ 

MSGFMT 

CONREM 

LSTXON 

LSTCTS 

DSKHDC 

DSKFDC 

CKTSLV 

CKT422 

RTCDRV 

NITDRV 



GEN for complex example 
standard master package 
non-banked program load 
to make requests of other sys 
needed by NETREQ 
no console on the master 
XON/XOFF for daisy (LSTDRA) 
CTS for matrix (LSTDRB) 
hard disk controller (DSKDRA) 
floppy disk control. (DSKDRB) 
circuit driver for slaves (CO) 
circuit drilfelP-r'or &S422 i£±} 
real-time clock driver 
hardware initialization driver 
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A Complex Example 
(Continued) 



Our system generation task is completed by 
creatina the comnanion OR MASTER. PAR file: 



; OSMASTER.PAR for complex example 
NMBCKT =2 ; 2 net circuits 

CKTAST = (0000) ,CKTDRA ; ckt for slaves 
(0100) f CKTDRB ; ckt 1 via RS422 



DSKAST = 00,DSKDRA 
00,DSKDRB 
01,DSKDRB 
80,(0101) 
81,(0101) 
82,(0101) 

PTRAST = 00,LSTDRA 
01,LSTDRB 
80,(0101) 
81,(0101) 

QUEAST = 

00,(0000) 
80,(0101) 

J fei7Wioij 

DEFDID = (0101) 
DSPPAT = 1,2,3,4 
MEMRES = (0400) 
NMBMBS = 0A 
NMBRPS = 5 
NMBSVC = 5 
NMBUFS =14 



drv A is local HD 

drv B is local FD0 

drv C is local FD1 

drv D is remote HD # 

drv E is remote FD0 

drv F is remote FD1 f 

ptr A is lcl daisy 

ptr B is lcl matrix 

ptr C is rmt dais,y p i_ 

ptr D is rmt matrix*" . . . 

queue B is local 
queue C is remote A 
queue D is remote B j|l 
default other master I 
assgn ptrs to queues 
IK safety margin 
10 message buffers 
5 reply packets 
5 server processes 
20 IK disk buffers 



The generation of the second master operating.)! 
system s could^be identical, except*4s^a.t alp«. 
occur rehcW of network addresses fDi'€0),anjS 
4r (0l01) ibj "the OSMASTER.PAR file would be 
reversed. Generation of the slave operating 
system would be very straightforward, and 
identical for both systems. 

If you study this example thoroughly until 
you understand the reason for every .GEN and 
.PAR file entry, you should have little 
trouble setting up your own "sysgens". 
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Sysgen Procedure To conclude this section, here is a suggested 

step-by-step procedure for generating a new 
version of TurboDOS: 

1. Bring up a previous version of TurboDOS. 
If this is your first attempt to generate 
a TurboDOS system, you may bring up CP/M 
instead. However, if you are using CP/M, 
all disks will have to be in a format 
compatible with both CP/M and TurboDOS 
(e.g*/ eight- inch one-sided single-density 
with 128-byte sectors). 

2. Make a working copy of your TurboDOS dis- 
tribution disk. Do not use the original 
disk (in case something goes wrong). 
Insert the working diskette in a conven- 
ient disk drive. 

3. Using your favorite text editor, create or 
revise the file OSMASTER.GEN containing 
the names of the relocatable modules to be 
linked together. Generally, this will 
consist of the appropriate STDxxxxx stan- 
dard package plus selected additional 
modules and all required device drivers. 

4. Using your editor once again, create or 
revise the file OSMASTER.PAR containing 
any required patches. This may be omitted 
if no patches are desired. 

5. Using the command GEN OSMASTER.SYS, gene- 
rate an executable system in accordance 
with the .GEN and .PAR files just con- 
structed. If your hardware has less than 
64K installed, don't forget to use the 
;Uxxxx option on the GEN command. If your 
hardware has banked memory, don't forget 
to use the ;Kxxxx option. 
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Sysgen Procedure 6. In a similar fashion, construct a new 

loader by creating or revising the files 
OSLOAD.GEN and OSLOAD.PAR, then using the 
command GEN OSLQAD.COM to generate the 
executable loader. 

7. For a master/slave network system, con- 
struct a slave operating system in the 
same manner. Create or revise the files 
OSSLAVE.GEN and OSSLAVE.PAR, then use the 
command GEN. OSSLAVE.SYS to generate the 
down-loadable slave operating system. 

8. To test the newly-generated system, eject 
all disks other than your working disk 
(again, in case something goes wrong). 
Enter the command Q5LQAD . The new system 
should cold-start. If it fails to come up 
or to function properly, you will have to 
start over at step 1 and check your work 
carefully — there is most likely an error 
in one of your .GEN or .PAR files, or a 
"bug" in one of your drivers. 
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(Intentionally left blank.) 
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DISTRIBUTION This section explains the TurboDOS distribu- 
tion procedure in detail. It covers TurboDOS 
licensing requirements, and the obligations 
of licensed distributors, dealers, and end- 
users. It describes how to make up and 
serialize TurboDOS distribution disks. 

Although this section is of concern primarily 
to licensed TurboDOS distributors, we've 
included it here so that dealers and end- 
users can gain a better perspective on the 
overall distribution process. 



TurboDOS Licensing TurboDOS is a proprietary software product of 

Software 2000, Inc. As such, it is protected 
by law against unauthorized use and reproduc- 
tion. Authorization to use and/or reproduce 
TurboDOS is granted only by written license 
agreement. 



Legal Protection TurboDOS programs and documentation are copy- 
righted, which means it is against the law to 
make copies without express written authori- 
zation from Software 2000 to do so. 

The word "TurboDOS" is a trademark owned by 
Software 2000 and registered in Class 9 (com- 
puter software) and Class 16 (documentation) 
with the trademark offices of the United 
States and most of the developed countries of 
the free world. This means it is against the 
law to make use of the TurboDOS trademark 
without express written authorization from 
Software 2000. 

Software 2000 has licensed certain companies 
to distribute TurboDOS. Such distributors 
are authorized to use the TurboDOS trademark, 
and to reproduce, distribute, and sub-license 
TurboDOS programs and documentation to deal- 
ers and end-users. 
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User Obligations TurboDOS may be used only after the user has 

paid the required license fee, signed a copy 
of the TurboDOS end-user license agreement, 
and returned the signed agreement to the 
issuing TurboDOS distributor. Then, TurboDOS 
may be used only in strict conformance with 
the terms of the license. 

Each end-user license allows TurboDOS to be 
used on one specific computer system identi- 
fied by make, model, and serial number. The 
end-user license may not be transferred from 
one computer system to another, and expressly 
forbids copying programs and documentation 
except as required for backup purposes only. 

A separate license fee must be paid and a 
separate license signed for each computer 
system on which TurboDOS is used. Network 
slave computers that cannot operate stand- 
alone do not have to be licensed separately 
from the network master. (This would be the 
case, for example, if the slave computers 
have no local disk storage, or if TurboDOS is 
furnished in a form that cannot be run stand- 
alone on the slave computers.) However, 
networked computers that are also capable of 
stand-alone operation under TurboDOS must 
each be licensed separately. 

Dealer Obligations A dealer must sign a TurboDOS dealer agree- 
ment and return the signed agreement to the 
issuing distributor. Then, the dealer is 
permitted to purchase pre-serialized copies 
of TurboDOS programs and documentation from 
the distributor, and to resell them to end- 
users. Dealers may not reproduce TurboDOS 
programs or documentation for any purpose. 
Before delivering each copy of TurboDOS, the 
dealer must see to it that the end-user signs 
the TurboDOS end-user license agreement and 
returns it to the issuing distributor. 
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Distributor Each licensed TurboDOS distributor is provi- 

nhl lnafinns rloH a masfor rnnu n-F TnrhAnfl.Q rplnrafahlp 
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modules and command programs on diskette. A 
distributor is allowed to reproduce and 
distribute copies of TurboDOS to dealers and 
end-users, but only in connection with 
certain specifically authorized hardware 
(usually manufactured or sold by the distri- 
butor). The distributor is required to 
serialize each copy of TurboDOS with a unique 
sequential magnetic serial number, and to 
register each serial number promptly with 
Software 2000. (Serialization is described 
in more detail below.) 

Each distributor is also provided with a 
master copy of TurboDOS documentation, either 
in camera-ready hardcopy or in ASCII files on 
disk. The distributor is responsible for 
reproducing the documentation and furnishing 
it with each copy of TurboDOS it issues. 

Zi di ef r i KnfAr miief v grcn i v a aaf Vi doal ar +■ r\ 

sign and return a TurboDOS dealer agreement 
before issuing copies of TurboDOS to the 
dealer for resale. A distributor must 
require each end-user to sign and return a 
TurboDOS end-user license agreement before 
issuing a copy of TurboDOS directly to the 
end-user. 
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Serialization Each copy of TurboDOS is magnetically serial- 
ized with a unique serial number. Such 
serialization helps ensure that reproduction 
and distribution of TurboDOS is done in 
strict accordance with the required licensing 
and registration procedures, and facilitates 
tracing of unlicensed copies of the software. 

Each relocatable module of TurboDOS distribu- 
ted to a dealer or end-user has a magnetic 
serial number composed of two parts: 

. an origin munkej: that identifies the 
issuing distributor, and 

a sequential unit number that uniquely 
identifies each copy of TurboDOS issued 
by that distributor. 

During system generation, the GEN command 
verifies that all modules making up a Turbo- 
DOS configuration are serialized consistent- 
ly, and magnetically serializes the resulting 
executable version of TurboDOS accordingly. 

The relocatable modules on the master disk 
furnished to each licensed TurboDOS distribu- 
tor are partially serialized with an origin 
number only. Each distributor is provided a 
serialization program (SERIAL.COM) that must 
be used to add a unique sequential unit num- 
ber to each copy of TurboDOS issued by the 
distributor. The GEN command will not accept 
partially-serialized modules that have not 
been serialized with a unit number. Con- 
versely, the SERIAL command will not re- 
serialize modules that have already been 
fully serialized. 
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"hot-lines" to provide TurboDOS technical 
assistance to its distributors. These are 
unlisted numbers providing direct access to 
the authors of the TurboDOS operating system, 
and are furnished only to licensed TurboDOS 
distributors. We encourage distributors to 
take advantage of this service whenever tech- 
nical questions or problems arise in using or 
configuring TurboDOS. 

It is the responsibility of each licensed 
distributor to provide technical support to 
its dealers and end-user customers. Software 
2 £ AHHfii assist dealers or end-users 
directly. Where exceptional circumstances 
seem to require direct contact between Soft- 
ware 2000 technical personnel and a dealer or 
end-user, this must be handled strictly by 
prior arrangement between Software 2000 and 
the distributor. 
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SERIAL Command 



Syntax 



Explanation 



Options 



The SERIAL command enables TurboDOS distribu- 
tors to magnetically serialize relocatable 
modules of TurboDOS for distribution. 



SERIAL srcefile destfile 
SERIAL ;Unnn {options} 



;Unnn {options} I 

I 
I 



The SERIAL command works exactly like the 
COPY command, and accepts exactly the same 
arguments and options. However, SERIAL has 
the additional function of magnetically 
serializing relocatable modules as they are 
copied. SERIAL serializes files of type .REL 
(Z80 modules) and type .0 (8086 modules). 
Other files are copied without any change. 

The unit number must be specified on the 
command line as ;Unnn, where n nnn n represents 
a decimal unit number in the range 0-65535. 
Unit numbers must be assigned sequentially, 
starting with 1. Unit number is reserved 
by convention for in-house use by the distri- 
butor. 

SERIAL produces fully-serialized modules that 
are encoded with the distributor's origin 
number and the specified unit number. GEN 
does not accept TurboDOS modules unless they 
have been fully serialized in this fashion. 



-J2pfc±ej3_J Explanation 



SERIAL accepts all COPY options, plus: 

;Unnn Relocatable modules (type .REL 
or .0) are magnetically serial- 
ized with unit number nnn, which 
must be a decimal integer in the 
range to 65535. This "option" 
is mandatory for SERIAL. 
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Example 



I 



i 0A1 SERIAL *.RE L B: :U289N 

OArAUTLOD .REL copied to 0B:AUTLOD, 
0A:AUTLOG .REL copied to 0B:AUTLOG. 



0A:SYSNIT. 
0A> 



REL 
REL 



REL copied to 0B:SYSNIT. REL 



Error Messages 



SERIAL incorporates all COPY error mes- 
sages, plus: 

Unit number not specified 
Origin number violation 
File is already serialized 
Unexpected EOF in .0 or .REL file 
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PACKAGE Command The PACKAGE command lets you combine any 

collection of relocatable modules into a 
single concatenated .REL file. 



Syntax 



I PACKAGE srcefile {destfile} 
I 



Explanation PACKAGE may be used to construct custom 

packages of TurboDOS modules, make additions 
or changes to the supplied STDxxxxx packages, 
pre-package collections of driver modules, 
and so forth. 

The "srcefile" argument specifies the name of 
an input file "srcefile. PKG" that lists the 
modules to be packaged. The "destfile" argu- 
ment specifies the name of the concatenated 
.REL file to be created. If "destfile" is 
omitted, then the "srcefile" argument is also 
used as the name of the output .REL file. 

If the .PKG file is found, it must contain 
the list of relocatable modules (.REL files) 
to be linked together. If the configuration 
file is not found, then the PACKAGE command 
operates in an interactive mode. You are 
prompted by an asterisk * to enter a series 
of directives from the console. The syntax 
of each directive is: 

I I 

I relfile { ,relf ile} . . . {;comment} I 



A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, PACKAGE concatenates all of 
the modules together (displaying the name of 
each module as it is encountered) and writes 
the result to the output file. 
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Example 



Error Messages 



I A } p_AC_KAGE Std LQadk 

I * ; STDLOADR. PKG standard loader package 

I * OSLOAD,LDRMSG,OSNTRY,FILMGR,FILSUP 

I * FILCOM,BUFMGR,DSKMGR,DSKTBL,NONFIL 

I * CONMGR,CONTBL,DSPSGL,COMSUB 

I OSLOAD LDRMSG OSNTRY FILMGR FILSUP etc. 

! 0A} 



File name missing from command 
Invalid input file name 
Non-privileged user 
Unexpected EOF in input file 
Disk is full 
Can't make output file 
Can't open input file 
No input files 
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Distribution Here is the procedure to be followed by dis- 
Procedure tributors when creating each copy of TurboDOS 

to be issued to a dealer or end-user: 

1. Assign a unique sequential unit number for 
this copy of TurboDOS, and register it 
immediately by filling out a serial number 
registration card (or agreed-to substi- 
tute) and mailing to Software 2000, Inc. 

2. Format a new disk, and label it with the 
following information clearly legible: 

. trademark TurboDOS R 

. version number (1.4x) 

. origin and unit numbers (oo/uuuu) 

. statutory copyright notice: 

Copyright 198x by Software 2000, Inc. 
All rights reserved. 

3. Use the SERIAL command to copy and serial- 
ize the appropriate files from your dis- 
tribution master disk to the new disk. 
Use the tables on the following page to 
guide you in determining what files to put 
on the new disk. 

IMPORTANT NOTE: Be absolutely certain 
that the new disk does n_p_t contain any 
unserialized modules or SERIAL.COM! 

4. Using the new serialized disk, use the GEN 
command to generate an executable loader 
and operating system. Follow the system 
generation procedure described in the 
previous section. 

5. In addition to the serialized disk, you 
should issue copies of TurboDOS documenta- 
tion and a start-up PROM (if applicable). 
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Distribution 

Frocedure 

(Continued) 



The following table may be used for guidance 

In addition to the files shown, you need to 
include hardware-dependent driver modules and 
utility programs as appropriate. 



1 single-user 1 


single-user 1 


multi-user 1 


1 w/o _spooJ_£x L 


with .spooler. _L 


jm£wj>xfciiijg i 


1 STDLOADR 


.REL 


STDLOADR 


.REL 


STDLOADR 


.REL 1 


1 STDSINGL 


.REL 


STDSINGL 


.REL 


STDSINGL 


.REL 1 


| - 




STDSPOOL 


.REL 


STDSPOOL 


.REL 1 


| - 




- 




STDMASTR 


.REL 1 


| — 




- 




STDSLAVE 


.REL 1 


I - 




— 




STDSLAVX 


.REL 1 


1 FASLOD 


.REL 


FASLOD 


.REL 


FASLOD 


.REL 1 


1 BNKMGR 


.REL 


BNKMGR 


.REL 


BNKMGR 


.REL 1 


1 CPMSUP 


.REL 


CPMSUP 


.REL 


CPMSUP 


.REL 1 


1 MPMSUP 


.REL 


MPMSUP 


.REL 


MPMSUP 


.REL 1 


1 RTCNUL 


.REL 


RTCNUL 


.REL 


RTCNUL 


.REL 1 


1 PATCH 


.REL 


PATCH 


.REL 


PATCH 


.REL 1 


i SUBMIT 


.REL 


SUBMIT 


.REL 


SUBMIT 


.REL i 


1 OSBOOT 


.REL 


OSBOOT 


.REL 


OSBOOT 


.REL 1 


| - 




- 




NETLOD 


.REL 1 


| - 




- 




NETREQ 


.REL 1 


| - 




- 




NETFWD 


.REL 1 


| - 




- 




BNKREQ 


.REL 1 


| — 




- 




MSGFMT 


.REL 1 


| - 




- 




NETSVC 


.REL 1 


| - 




- 




QUEMGR 


.REL 1 


I - 




- 




CONREM 


.REL 1 


1 AUTOLOAD 


.COM 


AUTOLOAD 


.COM 


AUTOLOAD 


.COM 1 


1 BACKUP 


.COM 


BACKUP 


.COM 


BACKUP 


.COM 1 


1 BANK 


.COM 


BANK 


.COM 


BANK 


.COM 1 


| - 




- 




BATCH 


.COM 1 


1 BOOT 


.COM 


BOOT 


.COM 


BOOT 


.COM 1 


1 BUFFERS 


.COM 


BUFFERS 


.COM 


BUFFERS 


.COM 1 


| - 




- 




CHANGE 


.COM 1 


1 COPY 


.COM 


COPY 


.COM 


COPY 


.COM 1 


1 DATE 


.COM 


DATE 


.COM 


DATE 


.COM 1 
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Distribution 

Procedure 

(Continued) 















1 single- 


user 1 


single-i 


aser 1 


multi-user 1 


L w/o_ spo 


pJLex. 1 


-wiili. .spooler 1 


network ina 1 


1 DELETE 


.COM 


DELETE 


.COM 


DELETE 


.COM 1 


1 DIR 


.COM 


DIR 


.COM 


DIR 


.COM 1 


1 DO 


.COM 


DO 


.COM 


DO 


.COM 1 


1 DRIVE 


.COM 


DRIVE 


.COM 


DRIVE 


.COM 1 


1 DUMP 


.COM 


DUMP 


.COM 


DUMP 


.COM 1 


1 ERASEDIR.COM 


ERASEDIR.COM 


ERASEDIR.COM 1 


1 - 




- 




FIFO 


.COM 1 


1 FIXDIR 


*COM 


FIXDIR 


.COM 


FIXDIR 


.COM 1 


1 FIXMAP 


.COM 


FIXMAP 


.COM 


FIXMAP 


.COM 1 


1 FORMAT 


.COM 


FORMAT 


.COM 


FORMAT 


.COM 1 


1 GEN 


.COM 


GEN 


.COM 


GEN 


.COM 1 


1 LABEL 


.COM 


LABEL 


.COM 


LABEL 


.COM 1 


1 — 




- 




LOGOFF 


.COM 1 


1 - 




- 




LOGON 


.COM 1 


1 — 




- 




MASTER 


.COM 1 


1 PRINT 


.COM 


PRINT 


.COM 


PRINT 


.COM 1 


1 - 




PRINTER 


.COM 


PRINTER 


.COM 1 


1 — 




QUEUE 


.COM 


QUEUE 


.COM 1 


1 — 




- 




RECEIVE 


.COM 1 


1 RELCVT 


.COM 


RELCVT 


.COM 


RELCVT 


.COM 1 


1 RENAME 


.COM 


RENAME 


.COM 


RENAME 


.COM 1 


1 - 




- 




SEND 


.COM 1 


1 SET 


.COM 


SET 


.COM 


SET 


.COM 1 


1 SHOW 


.COM 


SHOW 


.COM 


SHOW 


.COM 1 


1 TYPE 


.COM 


TYPE 


.COM 


TYPE 


.COM 1 


1 VERIFY 


.COM 


VERIFY 


.COM 


VERIFY 


.COM 1 
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CODING CONVENTIONS This section is devoted to in-depth discus- 
sion of TurboDOS internal coding conventions, 
aimed at the systems programmer writing hard- 
ware-dependent drivers or resident processes. 



Assembler Notes Drivers and resident processes for Z80 Turbo- 
DOS must be written using a Z80 assembler 
capable of producing relocatable modules with 
symbolic linkage information in the industry- 
standard Microsoft relocatable module format. 
Both Microsoft's M80 and Digital Research's 
RMAC assemblers produce object code in this 
format, and are fine choices for use with 
TurboDOS. 

Another excellent relocatable Z80 assembler 
is PASM from Phoenix Software Associates. 
However, PASM produces object modules in a 
non-standard format. 

To make it possible for PASM to be used with 
TurboDOS, a conversion utility (RELVCT.COM) 
for converting PASM object modules to stan- 
dard Microsoft format is furnished with 
TurboDOS. The command: 



I I 

I RELCVT filename I 

converts the specified PASM-format .REL file 
into Microsoft .REL format. During conver- 
sion, the character . is converted to ?, and 
the character % is converted to § wherever 
these characters appear in symbol names. 
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Assembler Notes 
(Continued) 



Programming examples and driver listings in 
this document are coded for PASM. If you are 
used to another assembler, please take note 
of certain syntax features of PASM which may 
be different in other assemblers. 

Names followed by # are external references 
to public names defined in other modules. 
Labels followed :: are public names available 
for reference in other modules. Some assem- 
bler s r equi r e such names to be declared usi ng 
an EXTERN or PUBLIC directive. 

Program, data, and common segments are intro- 
duced with a .LOC directive. Other assem- 
blers use different directives such as CSEG, 
DSEG, COMMON, etc. to accomplish the same 
thing. 

Finally, the symbol . represents the current 
location counter value. Some assemblers use 
$ or * instead. 



Undefined External 
References 



To allow various TurboDOS modules to be in- 
cluded or omitted at will, the GEN command 
automatically resolves all undefined external 
references to the default symbol public ?UND? 
(.UND. using PASM). The common subroutine 
module COMSUB contains the following subrou- 
tine: 



UND. : 



NOP 
NOP 
XRA 
RET 



two bytes of zero 

ii n n n 

clear A to zero 
done 



Thus, it is always safe to load or call an 
external name, whether or not it is present 
at GEN time. It is bad form to store into an 
undefined external name, however! 
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Memory Allocation 



<& 



The TurboDOS resident occupies the topmost 
portion of memory in a ZSO system, A common 
memory management module MEMMGR provides 
dynamic allocation and deallocation of memory 
space required for disk and message buffers, 
print queues, file and record locks, do-file 
nesting, and so forth. Memory segments are 
allocated downward from the base of the 
TurboDOS resident, reducing the space 
available for TPA. Deallocated segments are 
concatenated with any neighbors and threaded 
on a free-memory list. A best-fit algorithm 
is used to reduce memory fragmentation. 

Allocation and deallocation requests are 
coded in this manner: 



;code to allocate a memory segment 



MgC c°& 



LXI 

CALL 

ORA 

JNZ 

PUSH 



H,36 
ALLOC # 
A 
ERROR 

H 



;code to deallocate 
POP H 



;HL=segment size kt> «<-,o<?3& 

/allocate segment 1**^ A<-*- oC ## 

; alloc sucTeSSful? I OK A 

;NZ -> not enuf mem I5P ^tfJ^K 

;HL=sTgmfeffr&ldress I 

pj*H , S>au«.v fk ponio- k -fit, *f*lf . 

memory segment I 

;HL= segment address \*\ ^ ^%J«4. 



CALL DEALOC# ; deallocate segment I 



ALLOC* prefixes each allocated segment with a 
word containing the segment length, so that 
DEALOC* can tell how much memory is to be 
deallocated. ALLOC* does not zero the newly- 
allocated segment. 
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List Processing 



V ! 3 



TurboDOS maintains its dynamic structures as 
threaded lists with bidirectional linkages. 
This technique permits a node to be added or 
deleted anywhere in a list without searching. 
The list head and each list node have a two- 
word linkage (forward and backward pointers) . 

List manipulation is coded in this manner: 



.LOC .DATA.# ;data segment 
;list head (linkage initialized empty) 
LSTHED: .WORD LSTHED ; forward pointer 

.WORD LSTHED ;backward pointer 

;list node (linkage not initialized) 
LSTNOD: .WORD ; forward pointer 
.WORD ; backward pointer 
.BYTE [1283 ;contents of node 

.LOC .PROG.# ; program segment 
;code to add node to end of list 
LXI H, LSTHED ;HL=head 
LXI D, LSTNOD ;DE=node 
CALL LNKEND# ;link to 

;code to unlink node from list 
LXI H, LSTNOD ;HL=node 
CALL UNLINK* ;unlink 



address 
address 
list end 



address 
node 



;code to add node to beginning of list 
LXI H, LSTHED ;HL=head address 
LXI D,LSTNOD ;DE=node address 
CALL LNKBEG* ;link to list beg. 
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Task Dispatching 



TurboDOS incorporates a flexible, efficient 
mechanism for dispatching the Z80 processor 
among various competing processes. In coding 
drivers for TurboDOS, you must take extreme 

^aLC uu uoc unc uiopauwici. ^uj.icv«i.i^ xn utuct 

to attain maximum system performance. 

The dispatcher allows one process to wait for 
some event (for example, data-available or 
seek-complete) while allowing other processes 
to use the processor. For each such event, 
you must define a three-word structure called 
a "semaphore". 

A semaphore consists of a count-word followed 
by a two-word list head. The count-word is 
used by the dispatcher to keep track of the 
status of the event. (At present, only the 
LSB of the count word is used, supporting 
counts in the range -128 to +127.) The list 
head anchors a threaded list of processes 
waiting for the event to occur. 

Two primitive operations operate on a sema- 
phore: waiting for the event to occur 
(WAIT#), and signalling that the event has 
occurred (SIGNAL*). They are coded in this 
following manner: 



;this semaphore represents some event 



EVENT: .WORD 

.WORD EVENT+2 
.WORD EVENT+2 

;wait for the event to 

LXI H, EVENT 

CALL WAIT* 

1'-, !' ' ! 

; signal that event has 
LXI H, EVENT 
CALL SIGNAL* 



; semaphore count 
? semaphore f-ptr 
; semaphore b-ptr 

occur 

;HL=semaphore addr 
;wait for event 

occurred 

;HL=semaphore addr 
; signal event 
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Task Dispatching 
(Continued) 



Whenever a process waits on a semaphore, 
WAIT# decrements the semaphore's count-word. 
Thus, a negative count -N signifies that 
there are N processes waiting for the event 
to occur. Whenever an event is signalled, 
SIGNAL* increments the semaphore count-word 
and awakens the process that has been waiting 
longest. 

If an event is signalled but no process is 
waiting for it, then SIGNAL* increments the 
count-word to a positive value. Thus, a 
positive count N signifies that there have 
been N occurrences of the event for which no 
process was waiting. In this case, the next 
N calls to WAIT* on that semaphore will 
return immediately without waiting. 

Sometimes it is necessary for a process to 
wait for a specific time interval (for exam- 
ple, a motor-start delay or carriage-return 
delay) rather than for a specific event. 
TurboDOS provides a delay facility (DELAY*) 
that permits other processes to use the Z80 
while one process is waiting for such a timed 
delay. Delay intervals are specified as some 
number of "ticks". A tick is an implementa- 
tion-defined interval, usually 1/50 or 1/60 
of a second. Delays are coded thus: 



; delay for one- tenth of a second 

LXI H,6 ;HL=delay in ticks 

CALL DELAY* ; delay process 



Accuracy of delays is usually plus-or-minus 
one tick. A delay of zero ticks may be 
specified to relinquish the processor to 
other processes on a "courtesy" basis. 

All driver delays should be accomplished via 
WAIT* or DELAY*, ne_xex by spinning in a loop. 
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Interrupt Service 



Dispatching is especially efficient when used 
with interrupt-driven devices. Usually, the 
interrupt service routine just calls SIGNAL* 
to signal the interrupt-associated event. 

Most interrupt service routines should exit 
via the usual EI/RETI sequence. However, 
some periodic interrupt (usually a 50 or 60 
hertz clock interrupt) should have an inter- 
rupt service routine that exits by jumping to 
the dispatcher entrypoint ISRXIT* (without, 
enabling interrupts) to provide periodic 
time-slicing of processes. To avoid exces- 
sive dispatcher overhead, don't use ISRXIT# 
more than about 60 times per second. 

It is good programming practice for interrupt 
service routines to set up an auxilliary 
stack, in order to avoid the possibility of 
overflowing the stack area of some transient 
program. TurboDOS provides a standard inter- 
rupt stack area INTSTK# and stack pointer 
save location INTSP#. A simple interrupt 
service routine might be coded like this: 



save user SP 

;SP=aux stack 
save registers 



1 DEVISR: SSPD 


INTSP# 


1 LXI 


SP,INTSTK# 


1 PUSH 


PSW 


1 PUSH 


B ; 


1 PUSH 


D 


1 PUSH 


H ; 


1 'in 


PORT ; 


1 LXI 


H, EVENT ; 


1 CALL 


SIGNAL* ; 


1 POP 


H 


1 POP 


D ; 


1 POP 


B 


1 POP 


PSW 


1 LSPD 


INTSP# 


1 EI 




1 RETI 





reset interrupt 
HL=semaphore addr 
signal event 
restore registers 



restore user SP 
enable interrupts 
return from int. 
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Poll Routines 



Devices incapable of interrupting the Z80 
have to be polled by the driver. The dis- 
patcher maintains a threaded list of poll 
routines, and executes them every dispatch. 
The function of each poll routine is to check 
the status of its device, and to signal the 
occurrence of some event (for example, data- 
available) when it occurs. The routine 
LNKPOL* links a poll routine onto the poll 
list, and UNLINK* removes it. 

A poll routine must be coded so that it will 
not signal the occurrence of a particular 
event more than once. The best way to assure 
this is for the poll routine to unlink itself 
from the poll list as soon as it has signal- 
led the event. An example: 



EVENT: 



WORD 
WORD 
WORD 



; semaphore 

EVENT+2 

EVENT+2 



;driver waits for event 

LXI D,POLNOD ;DE=poll node addr 
CALL LNKPOL# ;activate poll rtn 
CALL POLRTN ; optional pretest 
LXI H, EVENT ;HL= semaphore addr 
CALL WAIT* ;wait for event 



;poll routine signals event when detected 

poll rtn linkage 

n ii ii 

get device status 
did event occur? 
if not, exit 
HL=semaphore addr 
signal event 
HL=linkage addr 
unlink poll rtn 
all done 



POLNOD : 


.WORD 


J 




.WORD 


; 


POLRTN: 


IN 


PORT ; 




AN I 


MASK ; 




RZ 






LXI 


H, EVENT j 


--.- 


CALL 


SIGNAL* ; 




LXI 


H, POLNOD ; 




CALL 


UNLINK* ; 




RET 





4-8 



TurboDOS 1.4 Z80 
Implementor ■ s Guide 



CODING CONVENTIONS 



Mutual Exclusion 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



Mn-t-nal Kirpliicinn 



■Pit r Hr»nn.Q i c fill 1 v ro-onfranf at- -I- h <=» nrnnoRc; 

and kernel levels. However, most driver 
modules are not coded re-entrantly (since 
most peripheral devices can only do one thing 
at a time). Consequently, most drivers must 
make use of a mutual-exclusion interlock to 
prevent TurboDOS from invoking them re-ent- 
rantly. 

This is very easy to accomplish using the 
basic semaphore mechanism of the dispatcher. 
It is only necessary to define a semaphore 
with its count-word initialized to 1 (instead 
of 0). Mutual exclusion may then be accom- 
plished by calling WAIT# upon entry and 
SIGNAL* upon exit. An example: 



;mutual-exclusion semaphore 

MXSPH: .WORD 1 ;count-word=l ! 

.WORD MXSPH+2 

•WORD MXSPH+2 



DRIVER: LXI H, MXSPH 
CALL WAIT* 



LXI H, MXSPH 
CALL SIGNAL* 
RET 



;HL=semaphore addr 
;wait if in-use 



;HL=semaphore addr 
;unlock mut-excl 
;done 



Interrupt Status 



To permit reliable testing of the interrupt 
status (enabled or disabled) of the Z80 CPU, 
TurboDOS provides the subroutine TSTIFF*. It 
is called with no arguments, and returns with 
the carry-flag set if and only if interrupts 
are disabled. 
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Sample Driver 
Using Interrupts 



Here is a simple device driver for an inter- 
rupt-driven serial input device. It illus- 
trates coding techniques discussed so far: 



1 MXSPH: 


.WORD 


1 


;MX semaphore 1 




.WORD 


MXSPH+2 






.WORD 


MXSPH+2 




1 RDASPH: 


.WORD 





;RDA semaphore 1 




-WORD 


RDASPH+2 






.WORD 


RDASPH+2 




1 CHRSAV: 


.BYTE 





; saved input char 1 


1 ;device 


driver main code 1 


1 INPDRV: 


:LXI 


H, MXSPH 


;HL=MX semaph addr 1 




CALL 


WAIT* 


;lock MX 1 




EI 




;need ints enabled 1 




LXI 


H, RDASPH 


;HL=semaphore addr 1 




CALL 


WAIT* 


;wait data avail 1 




LDA 


CHRSAV 


;get input char 1 




PUSH 


PSW 


;save on stack 1 




LXI 


H, MXSPH 


;HL=MX semaph addr 1 




CALL 


SIGNAL* 


; unlock MX 1 




POP 


PSW 


;return char in A 1 




RET 




;done 1 


1 ;interr 


upt service rout 


.ine 1 


1 INPISR: 


:SSPD 


INTSP* 


;save user's SP 1 




LXI 


SP,INTSTK# ;SP=aux stack 1 




PUSH 


PSW 


;save registers 1 




PUSH 


B 


. n ii | 




PUSH 


D 


s ii n 1 




PUSH 


H 


. n ii | 




IN 


PORT 


;get input char 1 




STA 


CHRSAV 


;save for driver 1 




LXI 


H f RDASPH 


;HL=semaphore addr 1 




CALL 


SIGNAL* 


;signal data avail 1 




POP 


H 


;restore registers 1 




POP 


D 


.H H 1 




POP 


B 


.ii ii 1 




POP 


PSW 


.ii ii 1 




LSPD 


INTSP* 


;restore user SP 1 




EI 




;enable interrupts 1 




RETI 




;return from int. 1 


' 


__..——— 
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Using Polling 



Hor-o 1 c 



ci mnl o rj£ST7T_r;e» rlriyoi 



rupting serial input device, 
how polling is used: 



•fqk nrt n~i n ^ ar ~ 
It illustrates 



1 MXSPH: 


.WORD 


1 


;MX semaphore 




.WORD 


MXSPH+2 






.WORD 


MXSPH+2 




1 RDASPH: 


.WORD 





;RDA semaphore 




.WORD 


RDASPH+2 






.WORD 


RDASPH+2 




1 CHRSAV: 


.BYTE 





; saved input char 


1 ; device 


driver main code 


1 INPDRV: 


:LXI 


H, MXSPH 


;HL=MX semaph addr 




CALL 


WAIT# 


;lock MX 




LXI 


D,POLNOD 


;DE=poll rtn node 




CALL 


LNKPOL* 


;activate poll rtn 




CALL 


POLRTN 


;optional pretest 




LXI 


H, RDASPH 


;HL=semaphore addr 




CALL 


WAIT* 


;wait data avail 




LDA 


CHRSAV 


;get input char 




PUSH 


PSW 


;save on stack 




LXI 


H, MXSPH 


;HL=MX semaph addr 




CALL 


SIGNAL* 


; unlock MX 




POP 


PSW 


; return char in A 




RET 




;done 


1 ; device 


poll ] 


routine wi 


th linkage 


1 POL NOD: 


.WORD 





;poll rtn linkage 




.WORD 







1 POLRTN: 


IN 


STATUS 


;get device status 




ANI 


MASK 


;data available? 




RZ 




;if not, exit 




IN 


DATA 


;get input char 




STA 


CHRSAV 


;save for driver 




LXI 


H, RDASPH 


;HL=semaphore addr 




CALL 


SIGNAL* 


; signal data avail 




LXI 


H,POLNOD 


;HL=linkage addr 




CALL 


UNLINK* 


;unlink poll rtn 




RET 




;done 
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Special Segments 



In addition to the usual code and data seg- 
ments, GEN command supports three special 
location counters (common blocks): 



M80/RMAC I PASM 



?INIT? 
?PAGE? 
?BANK? 



. INIT. # Initialization code 
.PAGE.# Page-boundary aligned 
.BANK.# Banked-memory common 



?INIT? Segment 



In coding driver modules, you will often find 
a considerable amount of initialization code 
that is executed only once at cold-start and 
never needed again. By assembling such code 
under ?INIT? (.INIT.# using PASM), it will be 
loaded and executed in lower memory (TPA) , 
and will not occupy space in the resident 
operating system. 



?PAGE? Segment 



Sometimes you may need to force a segment of 
code or data to begin on a 256-byte page 
boundary. Examples are the simulated CP/M 
BIOS branch table, and interrupt vectors for 
Z80 interrupt mode 2. By assembling under 
?PAGE? (.PAGE.* using PASM), the segment is 
guaranteed to be page-aligned. 



?BANK? Segment 



In banked-memory implementations, you need to 
be able to place certain code and data in the 
topmost part of memory which is common to 
both banks (not switched). Anything assem- 
bled under ?BANK? (.BANK.# using PASM) will 
be assigned to this common region (as speci- 
fied by the ;Kxxxx option on the GEN com- 
mand) . 
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xiiuer— irrocess 
Messages 



, V" 



xo pass messages irom one process to anotner, 
a five-word structure called a "message node" 
is used. A message node consists of a three- 
word semaphore followed by a two-word message 
list head. Routines are provided for sending 
messages to a message node (SNDMSG#), and 
receiving messages from a message node 
(RCVMSG#). Typically, the sending process 
allocates a memory segment in which to build 
the message, and the receiving process deal- 
locates the segment after reading the mes- 
sage. The first two words of each message 
must be reserved for a list-processing link- 
age. Coding is done in this manner: 



J 



;message node 
MSGNOD: .WORD 



.WORD MSGNOD+2 
.WORD MSGNOD+2 
.WORD MSGNOD+6 
.WORD MSGNOD+6 



semaphore part 



message list head 
it H H 



;one process allocates/builds/sends msg 



/ 



LXI 

CALL 

PUSH 

• 
• 

/POP 
LXI 
CALL 



H,12+4 
ALLOC* 
H 

D 

H, MSGNOD 

SNDMSG# 



HL=message size+4 
allocate segment 
save segment addr 
build msg in seg 
DE=message addr 
HL=msg node addr 
send message 



;other process reads/deallocates message 

LXI H, MSGNOD ;HL=msg node addr 

CALL RCVMSG* ; receive message 

PUSH H ;save message addr 

: ;process message 

POP H ;HL= segment addr 

CALL DEALOC# ; deallocate seg 
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Console Routines 



TurboDOS includes several handy console I/O 
subroutines which may be called from within 
driver modules as illustrated: 



;raw console I/O routines 



CALL 


CONST* 


ORA 


A 


RZ 




CALL 


CONINf 


CALL 


UPRCAS* 


MOV 


C,A 


CALL 


CONOUT* 



;get status in A 
; input char avail? 
;if not, exit 
f get input in ^A 
;make upper-case 
;C=character 
;output chr from C 



;message output routines 

;last char of message has sign-bit set 

CALL DMS# ; output following 
.ASCIS "This is a message" 
LXI H, MSG ADR f;HL=mes sage addr 
CALL DMSHL# §; output msg @ HL 

;binary-to-decimal output routine 

LXI H, 31416 ;HL=word value 
CALL DECOUT* ; displays decimal 



Sign-On Message 



You may add your own custom sign-on message 
to TurboDOS. Your message will be displayed 
at cold-start immediately following the nor- 
mal TurboDOS sign-on and copyright notice. 

Your sign-on message must be coded as an 
ASCII character string terminated with a $ 
delimiter, and labelled with the public entry 
symbol USRSOM. An example: 



USRSOM::.ASCII [ODH] [OAH] 

.ASCII "Implementation by " 

.ASCII "Trigon Computer Corp. 

.ASCII "$" 
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Resident Process 



You can r.n^P a rPsiHat . . 

the background concurrent with other system 
activities, and link it into TurboDOS. The 
create-process subroutine CRPROC* may be 
called to create such a process at cold-start 
as shown: 





.LOC 


.INIT.# 


1 HDWNIT: 


:LXI 


H,64 




CALL 


ALLOC* 




LXI 


D, MYPROC 




CALL 

• 


CRPROC* 




.LOC 


.PROG.* 


1 MYPROC: 


INR 


COUNT (Y) 




LXI 


D, 60*60 




MVI 


C,2 




CALL 


OTNTRY* 


i 
i 


Tifn 


MYPROC 



init code 
HL=workspace size 
alloc workspace 
HL=workspace addr 
DE=entrypoint add 
create process 



;code segment 
; increment counter 
;1 minute in ticks 
;T-function 2 
;delay 1 minute 
;loop forever 



CRPROC* automatically allocates a TurboDOS 
process area (address appears in registerJX) 
and a stack area (address appears in SP). If 
the process requires a re-entrant workspace, 
it should be allocated with ALLOC* and passed 
to CRPROC* in HL (as shown above), and will 
appear to the new process in register] Y. 

The resident process must make all operating 
system requests by calling OCNTRY* or OTNTRY* 
with a C-function or T-function number 
^register C. It m.u.St not call location 0005H 
or 0050H in the base page, nor make direct 
calls on kernel routines such as WAIT*, 
SIGNAL*, DELAY*, SNDMSG*, RCVMSG*, ALLOC*, 
and DEALOC*. 
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Resident Process A resident process is not attached to a con- 
(Continued) sole, so any console I/O requests will be 

ignored. 

You can do file processing within a resident 
process, using the normal C-functions open, 
close, read, write, and so forth, called via 
OCNTRY#. First, however, you must remember 
to warm-start with C-function (OCNTRY#), 
and then log-on with T-f unction 14 (OTNTRYt). 



A resident process must always be coded to 
preserve the contents of index register X, 
which Turbodos relies upon as a pointer to 
its process area. The process may use all 
other registers as desired. 



User -De fined The User-Defined Function (T-function 41) 

Function provides a means of adding your own special 

functions to the normal TurboDOS repertoire 
of C-fuhctions and T-functions. To do this, 
you simprv create a function processor sub- 
routine wi%^ the public entrypoint symbol 
USRFCN. 

■V. ^ 

-\ : ^ Whenever a program invokes T-function 41, 
■v." TurboDOS transf ersvcontrol to your USRFCN 
f.. y; routine. On entry, register BC contains the 

address of the 128-byce record area passed 
from the caller's current^ DMA address, and 
registers DE and HL contaiXwhatever values 
the caller loaded into theitv^ Your USRFCN 
routine may return data to theN^aller in the 
128-byte record area (address in N B^ at entry) 
and in any of the registers A-B-C-tKE-H-L. 

Architecturally, your USRFCN routine Is in- 
side the TurboDOS kernel. Consequently, it 
may call kernel subroutines directly. Any 
calls to C-functions and T-functions must 
therefore be made by means of two special 
recursive entrypoints: XCNTRY# and XTNTRY#. 
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DRIVER INTERFACE This section explains how to code hardware- 
dependent device driver modules, and presents 
formal interface specifications for each 
category of driver required by TurboDOS. 

Following this section is a large appendix 
that contains assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for your 
driver development work. 



General Notes Drivers modules are coded with standard pub- 
lic entrypoint names, and linked to TurboDOS 
using the GEN command. You may package your 
drivers into as many or few separate modules 
as you like. In general, it is easier to 
reconfigure TurboDOS for a variety of devices 
if the driver for each device is packaged as 
a separate module. 

TurboDOS is designed to accomodate multiple 
disk, console, printer, and network drivers. 
For disk drivers, for instance, the DSKAST 
is normally set up to refer to disk driver 
entrypoints DSKDRA#, DSKDRB#, DSKDRC#, and so 
forth. Each disk driver should be coded with 
the public entrypoint DSKDR@ (DSKDR% using 
PASM). The GEN command automatically maps 
successive definitions of such names by 
replacing the trailing @ by A, B, C, etc. 
The same technique may be used for console, 
printer, and network driver entrypoints. 

You must code driver routines to preserve the 
stack and index registers X and Y, but you 
may use other registers as desired. 
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Initialization Hardware initialization and interrupt vector 

set-up should be performed in an initializa- 
tion routine labelled with the public entry 
symbol HDWNIT::. TurboDOS calls this routine 
during cold-start with interrupts disabled. 

Your HDWNIT:: routine must not enable inter- 
rupts or make calls to WAIT* or DELAY*. In 
most cases, HDWNIT:: will contain a series of 
Galls to individual driver initialization 
subroutines contained in other modules. 

One-time initialization code that is not 
needed again should be assembled under the 
special location counter ?INIT?, so that it 
doesn't take up space in the resident opera- 
ting system. 
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public entry symbol C0NDR@ (C0NDR%:: using 
PASM). A console number (from CONAST) is 
passed in register B. The driver must per- 
form a console I/O operation according to the 
operation code passed in register E: 



l_E-reg 1 


Function 


1 


Return status in A, char in C 


1 1 


Return input character in A 


1 2 


Output character passed in C 


1 8 


Enter error-message mode 


1 9 


Exit error-message mode 


1 10 


Conditional output char in C 



If E=0, the driver determines if a console 
input character is available. If no charac- 
ter is available, the driver returns A=0. If 
an input character is available, the driver 
returns A=-l and the input character in C, 
Mt JBiiSi nafc Aconsume" £te character . Turbo- 
DOS depends upon this look-ahead capability 
to detect attention requests. The driver 
must not dispatch (via WAIT* or DELAY*) when 
processing an E=0 call. 

If E=l, the driver obtains an input character 
(waiting if necessary) and returns it in A. 

If E=2, the driver displays the output char- 
acter passed in C (waiting if necessary). 

If E=8, the driver prepares to display a 
TurboDOS error message; if E=9, it reverts to 
normal. TurboDOS always precedes each error 
message with an E=8 call and follows it with 
an E=9 call. This gives the driver an oppor- 
tunity to take special action (25th line, 
reverse video, etc.) for error messages. For 
simple consoles, the driver should output a 
CR-LF in response to E=8 and E=9 calls. 
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Console Driver If E=10, the driver determines whether or not 
(Continued) it can accept a console output character 

without dispatching (via WAIT# or DELAY*). 
If so, it outputs the character passed in C, 
and returns A=-l to indicate that the charac- 
ter was accepted. However, if the driver 
cannot accept a console output character 
without dispatching, it returns A=0 to indi- 
cate that the character was not accepted; 
TurboDOS will then make an E=2 call to output 
the same character. This special conditional 
output call is used by TurboDOS to optimize 
console output speed by avoiding certain 
dispatch-related overhead whenever possible. 

You should make a special effort to code the 
console driver to execute the minimum number 
of instructions possible, especially func- 
tions 0, 2, and 10. Excessive use of subrou- 
tine calls, stack operations, and other time- 
consuming coding techniques can make the 
difference between running the console device 
at full rated speed or something less. Study 
the sample driver listings in the appendix 
with this in mind. 
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A printer driver should be labelled with the 
public entry symbol LSTDR@ (LSTDR%:: using 
PASM). A printer number (from PTRAST) is 
passed in register B. The driver must per- 
form a printer output operation according to 
the operation code passed in register E: 



.JErX&fl-J 



- PHH-C^iPH- _ 



2 Print character passed in C 

7 Perform end-of-print-job action 



If E=2, the driver prints the output charac- 
ter passed in C (waiting if necessary). 

If E=7, the driver takes any appropriate end- 
of-print-job action. This is quite hardware- 
dependent, and may include slewing to top-of- 
form, homing the print head, dropping the 
ribbon, and so forth. 
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Disk Driver 



A disk driver should be labelled with the 
public entry symbol DSKDR@ (DSKDR%:: using 
PASM). The driver performs the physical disk 
operation specified by the Physical Disk 
Request (PDR) packet whose address is passed 
by TurboDOS in index register X. The struc- 
ture of the PDR packet is: 



1 Offset 1 


£DDtSDt3 1 


I 

1 ;physical disk request 


(PDR) packet 1 


1 0(X) 


.BYTE 


OPCODE 


; operation code 1 


1 1(X) 


.BYTE 


DRIVE 


;drive (base 0) 1 


1 2(X) 


.WORD 


TRACK 


;track (base 0) 1 


! 4(X) 


.WORD 


SECTOR 


;sector (base 0) 1 


1 6(X) 


.WORD 


SECCNT 


;#sectors to rd/wr 1 


1 8(X) 


.WORD 


BYTCNT 


;#bytes to rd/wr 1 


1 10 (X) 


.WORD 


DMAADR 


;DMA addr to rd/wr 1 


1 12(X) 


.WORD 


DSTADR 


;DST address 1 


1 ;copy 


of disk 


specification table (DST) 1 


1 14 (X) 


.BYTE 


BLKSIZ 


;block size (3-7) 1 


1 15(X) 


.WORD 


NMBLKS 


;#blocks on disk 1 


1 17 (X) 


.BYTE 


NMBDIR 


;#directory blocks 1 


1 18 (X) 


.BYTE 


SECSIZ 


;sector size (0-7) 1 


1 19 (X) 


.WORD 


SECTRK 


; sectors per track 1 


1 21 (X) 


.WORD 


TRKDSK 


;tracks on disk 1 


1 23 (X) 


.WORD 


RESTRK 


;reserved tracks 1 



The operation to be performed by the driver 
is specified in the first byte of the PDR 
packet (OPCODE) as follows: 



OPCODE 1 



F unction 



Read sectors from disk 
Write sectors to disk 
Determine disk type, return DST 
Determine if drive is ready 
Format track on disk 
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Disk Driver 
(Continued) 



aj. v/t v/v/wa-u/ cue ulivcl i. caufi ocj^^inx pnysiUdl 

sectors (or equivalently, BYTCNT bytes) into 
DMAADR, starting at TRACK and SECTOR on 
DRIVE. The driver returns A=0 if the opera- 
tion is successful, or A=-l if an unrecover- 
able error occurs. TurboDOS may request 
multiple consecutive sectors to be read, but 
will never request an operation that extends 
past the end of the track. 

If OPCODE=l, the driver writes SECCNT physi- 
cal sectors (or BYTCNT bytes) from DMAADR, 
starting at TRACK and SECTOR on DRIVE. The 
driver returns A=0 if the operation is suc- 
cessful, or A=-l if an unrecoverable error 
occurs. TurboDOS may request multiple con- 
secutive sectors to be written, but will 
never request an operation that extends past 
the end of the track. 

If OPCODE=2, the driver must determine the 
type of disk mounted in DRIVE, and must 
return, in the DSTADR field of the PDR 
packet, the address of an 11-byte disk speci- 
fication table (DST) structured as follows: 



PffPfij^JL Description 



block size (3=1K,4=2K,. . . ,7=16K) 

1-2 total number of blocks on disk 

3 number of directory blocks 

4 sector size (0=128, ... ,7=16K) 
5-6 number of sectors per track 
7-8 number of tracks on the disk 
9-10 number of reserved (boot) tracks 



The first byte of the DST (BLKSIZ) specifies 
the allocation block size in bits 2-0. In 
addition, bit 7 is set if the disk is fixed 
(non-removable), and bit 6 is set if file 
extents are limited to 16K (EXM=0) . 
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Disk Driver The driver returns A=-l if the operation is 
(Continued) successful, or A=0 if the drive is not ready 

or the disk type is unrecognizable. On 
successful return, TurboDOS moves a copy of 
the DST into 14 (X) through 24 (X), where it is 
available for subsequent operations. 

If OPCODE=3, the driver determines whether 
DRIVE is ready, and returns A=-l if it is 
ready or A=0 if not. 



If OPCODE=4, the driver formats (initializes) 
TRACK on DRIVE, using hardware-dependent 
formatting information at DMAADR (put there 
by the FORMAT command). The driver returns 
A=0 if successful, or A=-l if an unrecover- 
able error occurs. 
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select driver labelled with the public entry 
symbol SELBNK::. The function of this rou- 
tine is simply to select the memory bank (0 
or 1) passed in register A. The routine 
should be coded under the special location 
counter ?BANK? to ensure it is situated in 
unswitched common memory. In addition, the 
SELBNK:: routine must preserve all registers 
other than A. 

All interrupt-driven drivers in a banked- 
memory system must be designed to service 
interrupts properly regardless of which bank 
is active when an interrupt occurs. Drivers 
for DMA disk controllers must ensure that DMA 
operations transfer into or out of bank 
only. Study the sample drivers in the appen- 
dix for suggested techniques. 
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Network Driver 



A network circuit driver should be labelled 
with the public entry symbol CKTDR@ (CKTDR%:: 
using PASM). A message buffer address is 
passed in register DE. The driver must 
either send or receive a network message, 
according to the operation code passed in 
register C: 



— A*— Jr i^ajj ■/,— ■■ pi.,^ 



EUIl££i£IL 



Receive message into buffer at DE 
Send message from buffer at DE 



If C=0, the driver receives a network message 
into the message buffer whose address is 
passed in DE (waiting if necessary). If a 
message is received successfully, the driver 
returns A=0. If an unrecoverable malfunction 
of any remote processor is detected, the 
driver returns A=-l with the network address 
of the crashed processor in DE. 

If C=l, the driver sends a network message 
from the message buffer whose address is 
passed in DE. If the message is sent suc- 
cessfully, the driver returns A=0. If the 
message could not be sent because of an unre- 
coverable malfunction of the destination 
processor, the driver returns A=-l with the 
network address of the crashed processor in 
DE. 

The structure of a network message buffer is 
shown on the next page. The first two words 
of the buffer are reserved for a linkage used 
by TurboDOS, and should be ignored by the 
driver. The 11-byte message header and 
variable-length message body should be sent 
or received over the circuit. The driver 
needs to look at only the first two header 
fields (MSGLEN and MSGDID) and possibly the 
last field (MSGFCD). 
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Network Driver 
(Continued) 



i ; message buffer format 


1 .WORD ? 


;linkage (ignored) 


1 .WORD ? 


. n ii 

r 


1 ? 11-byte message header 


1 .BYTE MSGLEN 


;msg length 


1 .WORD MSGDID 


; destination addr 


1 .BYTE MSGPID 


;process id 


! .WORD MSGSID 


; source addr 


1 .WORD MSGOID 


;originator addr 


1 .BYTE MSGOPR 


;orig'r process id 


I .BYTE MSGLVL 


;forwarding level 


1 .BYTE MSGFCD 


;msg format code 


1 ; variable-length body 




1 .BLKB 7 


; registers ACBEDLH 


1 .BLKB 1 


;user # and flags 


1 .BLKB 37 


; optional FCB data 


1 .BLKB 128 


; optional record 



The message format code field MSGFCD contains 
bit-encoded flags that define the format and 
context of each network message. This field 
may be ignored by most simple drivers, but 
its contents may be useful in complex network 
environments. Encoding of MSGFCD is: 



-3l±-J leaning 



first message of session 

1 last message of session 

2 continuation message follows 

3 request includes FCB data 

4 request includes record data 

5 reply includes FCB data 

6 reply includes record data 

7 this is a reply message 
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Network Driver The length field MSGLEN represents the number 
(Continued) of bytes in the message, including the header 

and body (but excluding the linkage). On a 
receive request (C=0), TurboDOS presets 
MSGLEN to the maximum allowable message 
length, and expects MSGLEN to contain the 
actual message length on return. On a send 
request (C=l), TurboDOS presets MSGLEN to the 
actual length of the message to be sent. 



In a master/slave network, it is often desir- 
able for the circuit driver in the master to 
periodically "poll" the slave processors on 
the circuit to detect any slave malfunctions 
quickly and to effect recovery. If the 
driver reports that a slave has crashed (by 
returning A=-l and DE=network-address), then 
the circuit driver must not accept any fur- 
ther messages from that slave until TurboDOS 
has completed its recovery process. 

TurboDOS signals the driver that such recov- 
ery is complete by sending a dummy message 
destined for the slave in question with a 
length of zero. The driver should not actu- 
ally send such a message to the slave, but 
could initiate whatever action is appropriate 
to reset the slave and download a new copy of 
the slave operating system. 

A slave must request an operating system 
download by sending a special download re- 
quest message to the master (usually done by 
a bootstrap routine). The download request 
message consists of a standard 11-byte header 
(with MSGPID, MSGOID and MSGFCD zeroed) fol- 
lowed by a 1-byte body containing a "download 
suffix" character. The master processor 
addressed by MSGDID will return a reply mes- 
sage whose 128-byte body is the first record 
of the download file OSSLAVEx.SYS (where "x" 
is the specified download suffix). 
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Network Driver The slave continues to send download request 
(Continued) messages and to receive successive download 

records until it receives a short reply mes- 
sage (1-byte body) signifying end-of-file. 
The first word of the downloaded file speci- 
fies the base address to which the downloaded 
system should be moved? and the second word 
specifies the total byte-length of the sys- 
tem. The single byte passed as the body of 
the final short message identifies the system 
disk, and should be passed to the system in 
register A. 

The entire failure detection, failure recov- 
ery, and slave downloading procedure is very 
hardware-dependent. Study the driver listing 
in the appendix for guidance. 
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Cobud Driver 



The comm driver supports the TurboDOS commu- 
nications extensions (T-functions 34-40), and 
may be omitted if these functions are not 
used. The driver should be labelled with the 
public entry symbol COMDRV::. A comm channel 
number is passed in register B. The driver 
must perform an I/O operation according to 
the operation code passed in register E: 



Return input status in A 

1 Return input character in A 

2 Output character passed in C 

3 Set channel baud rate from C 

4 Return channel baud rate in A 

5 Set modem controls from C 

6 Return modem status in A 



If E=0, the driver determines if an input 
character is available. If one is available, 
the driver returns A=-l, otherwise A=0. 

If E=l, the driver obtains an input character 
(waiting if necessary) and returns it in A. 

If E=2, the driver outputs the character 
passed in C 

If E=3, the driver sets the channel baud rate 
according to the baud-rate code passed in C. 
If E=4, the driver returns the channel baud- 
rate code in A. See T-functions 37 and 38 
in the Z3D FX£>3iamm&X±S fiUJLfle for baud-rate 
code definitions. 

If E=5, the driver sets the modem controls 
according to the bit-vector passed in C. If 
E=6, the driver returns the modem status 
vector in A. See T-functions 39 and 40 in 



the Z80 
definitions. 



LJBBejLLS 



for bit-vector 



5-14 



TurboDOS 1.4 Z80 
Iinpleinentor " s Guide 



DRIVER INTERFACE 
Clock Driver 



Copyright 1984 by Software 2000, Inc. 
All rights reserved. 



VXWVA 1/lXVCIi 



Tue real— time clock di.ivei. does not take the 
form of a subroutine called by TurboDOS, as 
do the other drivers described in this sec- 
tion. Rather, the clock driver generally 
consists of an interrupt service routine 
which responds to interrupts from a periodic 
interrupt source (preferably 50 to 60 times a 
second). The interrupt service routine 
should call DLYTIC# once per system tick (to 
synchronize DELAY* requests). It should also 
call RTCSEC# once per second (that is, every 
50 to 60 ticks) to update the system time and 
date. Finally, it should exit by jumping to 
ISRXIT# to provide a periodic dispatcher 
time-slice. Excluding initialization code, a 
typical clock driver might be coded thus: 



1 RTCCNT: 


.BYTE 


60 


1 RTCISR: 


SSPD 


INTSP* 




LXI 


SP,INTSTK# 




PUSH 


PSW 




PUSH 


B ; 




PUSH 


D ; 




PUSH 


H ; 




IN 


PORT ; 




CALL 


DLYTIC* ; 




LXI 


H, RTCCNT ; 




DCR 


M ; 




JRNZ 


..X 




MVI 


M,60 




CALL 


RTCSEC# ; 


1 ..X: 


POP 


H ; 




POP 


D ; 




POP 


B ; 




POP 


PSW ; 




LSPD 


INTSP# 




JMP 


ISRXIT# ; 



divide-by-60 cntr 
save user's SP 
;SP=aux stack 
save registers 



reset interrupt 
signal one tick 
get div-by-60 cnt 
decrement counter 
not 60 ticks yet 
reset counter 
signal one second 
restore registers 



restore user's SP 
go to dispatcher 
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Clock Driver 
(Continued) 



If the hardware is capable of determining the 
date and time-of-day at cold-start (by means 
of a battery-powered clock, for example), the 
clock driver may initialize the following 
public symbols in the RTCMGR module: 



SECS: 
MINS: 
HOURS 
JDATE 



.BYTE 

.BYTE 

.BYTE 

.WORD 8001H 



; seconds 0-59 
;minutes 0-59 
; hours 0-24 
;Julian date 
;base 31-Dec-47 
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Bootstrap The bootstrap is usually contained in a ROM 

or on a boot track. its function is to 
search all disk drives for the TurboDOS 
loader program OSLOAD.COM, and to load and 
execute it if found. To generate a boot- 
strap, use the GEN command to combine the 
standard bootstrap module OSBOOT with your 
own hardware-dependent driver. Your driver 
must define the following public entry sym- 
bols: INIT, SELECT, READ, XFER, and RAM. 

INIT:: is called once to perform any required 
hardware initialization. It returns with the 
load base address (where 0SL0AD.COM will be 
loaded) in HL. This address should normally 
be 0100H, but may have to be higher for a 
bootstrap ROM in low-memory. 

SELECT:: is called to select the disk drive 
passed in A (0-15). If the selected drive is 
not ready or non-existent, it returns A=0. 
Otherwise, it returns A=-l and the address of 
an 11-byte disk specification table (DST) in 
HL. The DST format is described on page 5-7. 

READ:: is called to read one physical sector 
from the last-selected drive. The track is 
passed in BC, the sector in DE, and the DMA 
address in HL. It must return A=0 if suc- 
cessful, or A=-l if an unrecoverable error 
occurred. 

XFER:: is transferred to at the end of the 
bootstrap process. In most cases, it needs 
only to set location 0080H to zero (to 
simulate a null command tail) and jump to 
0100H. However, if INIT returned a loader 
base other than 0100H, then XFER must move 
the loader down to 0100H before executing it. 

RAM:: defines a 64-byte area that OSBOOT can 
use for working storage. It should not be 
located where 0SL0AD.COM will be loaded! 
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Source Listings 



The remainder of this document consists of 
assembler source listings of actual drivers. 
The listings comprise the drivers for a 
networking TurboDOS system. The master 
processor is an S-100 single board computer, 
which incorporates 128K of banked memory, a 
floppy disk controller (supporting both 5 ra 
and 8" drivers), and a pair of RS232 serial 
ports on-board. The master also has a hard 
disk controller board connected to a pair of 
Winchester drives. The slave processors are 
S-100 single-board computers with 128K of 
banked memory and a pair of RS232 serial 
ports. 

The listings appear in the following order: 



-KfiduJ^J Be^cjLipjkisn 



EQUATE common symbolic equates 

MPBMAS master bootstrap driver 

NITMAS master driver initialization 

INTMAS master interrupt handler 

BNKMAS master bank-select driver 

CON192 serial console driver, 19.2KB 

LSTCTS serial printer driver, CTS 

LSTETX serial printer driver, ETX/ACK 

LSTXON serial printer driver, XON/XOFF 

SPDMAS master serial/parallel driver 

RTCMAS master clock driver 

DSKFDC master floppy disk driver 

DSTFDC DSTs for 5" and 8" floppy disks 

DSKHDC Winchester hard disk driver 

MCDMAS master circuit driver 

NITSLV slave driver initialization 

BNKSLV slave bank-select driver 

SCDSLV slave circuit driver 

RTCSLV slave clock driver 

SPDSLV slave serial/parallel driver 

SLVRES general slave-reset subroutine 
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Note: Sample driver source listings are available. upon request. 
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